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Preface 

April 1979 



This document describes configurations of the Alto/Mesa system software and the individual 
components which comprise them. These components include runtime support for the language, 
routines for manipulating the Alto display, keyboard, and file system, facilities for loading client 
programs and building new systems, and a number of useful common software packages. 

Suggestions as to the form, correctness, and understandability of this material should be funneled 
through your support group. All of us involved in the development of Mesa welcome feedback and 
suggestions on both the language and the system and debugging environment. 



1. Overview 



The Alio/Mesa environment contains all of the facilities described in this document. Section 2 
contains an enumeration of the definitions modules available in the Alto/Mesa system; it includes a 
brief description of the facilities provided by each interface. Complete documentation can be found 
in Section 5. 

Section 3 describes the various configurations and optional packages that comprise the Alto/Mesa 
system. Two configurations of the system are available: the standard one, which includes most of 
the facilities described here, and a more basic one, containing only required runtime and file system 
support (it contains no display or keyboard software, for example). A number of optional packages 
are available for use with the basic system, so that the Mesa system can be tailored to each 
applicauon. 

The Mesa Executive (Section 4) is a simple (and small) user interface supporting only a few 
commands. It allows only program loading, state saving, and debugger communication; more 
complicated operations must be provided by the user or by one of the standard packages that is 
available separately. The Mesa Executive also supports command line input in both the standard 
and the basic system; this allows the user interface to be completely controlled by the application. 

Finally, the bulk of this manual (Section 5) contains detailed descriptions of each of the packages 
summarized in Section 2. 

Further details are available elsewhere on the language {Mesa Language Manual) and the debugger 
{Mesa Debugger Documentation). Information on obtaining and running the system is contained in 
the Mesa User*s Handbook. 



2. Definitions and Interfaces 



The following list enumerates the public system modules of interest to Alto/Mesa programmers. 
The interface name is followed by tlie title of the section of this document (or other reference 
material) which describes the facilities the interface provides. The parenthesized names following 
the DEFINITIONS module identify the programs which implement that interface - the ultimate 
documentation after all. 

AllocDefs (Swapper) Segment Package 

Low level memory allocation functions are defined here. Complete control of segment allocation 
and swapping can be obtained using this interface. 

AltoDefs (Hardware) Mesa Language Manual 

Contains a number of machine dependent constants describing physical characteristics of the Alto 
and its basic data types (bits per character, characters per word, etc.). 

AltoDisplay (Hardware) Alto: A Personal Computer System; Hardware Manual 

Provides a Mesa definition of the properties of the Alto display: its dimensions, Resolution, 
Background, the DCB chain, and the DCB format. A LongDCB has been added for interim 
use on the DO. 

AltoFileDefs (BCPL) Alto Operating System Reference Manual 

Defines the data structures (but not the operations) used in manipulating the Alto file system. Note 
that these structures are shared by several software systems amning on the Alto. 

BitBltDefs (Hardware) Alto: A Personal Computer System: Hardware Manual 

Provides a Mesa definition of the hardware BitBlt (bit boundary block transfer) operation. A 
LongBBTable has been added for interim use on the DO. 

DirectoryDefs (Directory) Directory Package 

Common operations on the Alto's file directory are defined here; they are all based on a single 
primitive which enumerates entries in a directory. 

DisplayDefs (SystemDisplay, DisplayControl) Display Package 

Provides device-dependent operations for the display. Simple operations are implemented using the 
standard stream interface (see StreamDefs). 

DoubleDefs (Double) Miscellaneous 

Contains a complete set of procedures for operating on long (double precision) cardinals (see also 
InlineDefs). This package is no longer supported, since long cardinals are fully supported by 
the language. 
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FontDefs (AlFont) Display Package 

Defines a uniform interface for all font formats. It includes facilities for dynamically swapping font 
files. 

FrameDefs (Miscellaneous, Modules, Swapper, UnNewConfig) Modules 

Provides low level operations on modules and their runtime representation (global frames). It 
includes facilities for controlling residency of a module's code segment and for loading and 
unloading configurations. 

FSPDefs (FSP) Storage Management 

This memory allocation package provides temporary storage for small, transient data stmctures 
whose size is not known at compile time. 

ImageDefs (Checkpoint, Makelmage) Image Files 

Image files are used to save tlie state of a computation so that it can be restarted later (perhaps in a 
different environment). Different types of image files can be created using the procedures defined 
in this interface; each type makes different assumptions about the state of the environment when it 
is restarted. 

InlineDefs (InllneDefs) Miscellaneous 

Defines a set of instructions not accessible at the language level. Logical operations and some 
extended precision arithmetic is included. 

lODefs (StreamlO) StreamlO Package 

A simple Teletype style I/O interface is provided by these procedures. Minimal editing and input 
and output conversion routines are included. 

KeyDefs (Keyboard, KeyStreams) Keyboard Package 

Provides device-dependent operations for die keyboard, keyset, and mouse. Simple operations are 
implemented using the standard stream interface (see StreamDefs). 

MiscDefs (Miscellaneous) Miscellaneous 

A set of miscellaneous but useful procedures that don't obviously belong in any of the other 
interfaces. 

Mopcodes (Hardware) OIS Processor Principles of Operation 

Defines the opcode numbers used by the Mesa instruction set. It is useful when inline procedures 
need to be defined to obtain access to machine facilities not available in the language. 

OsStaticDefs (BCPL) Alto Operating System Reference Manual 

Defines information available through the Alto Operating System Swat resident. 

ProcessDefs (Process) Processes and Monitors 

Includes a number of extensions to the language facilities for processes, monitors, and condition 
variables. Priorities and timeouts can be adjusted, and processes can be detached and aborted. 
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RealDefs (not implemented) Miscellaneous 

Defines the procedure calls generated by the compiler for operating on real data types. (Mesa 
does not provide an implementation of this interface.) 

SegmentDefs (Segments, Files, Swapper) Segment and File Packages 

Operations on data and file segments are contained here; tliis includes virtual memory management 
and swapping. Basic operations on files and their attributes are also included. 

StreamDefs (KeyStreams, StreamsA, StreamsB) Disk, Display, Keyboard, and Streams 
Packages 

Defines the operations common to all streams. It also includes some device-dependent operations 
unique to the disk, keyboard, and display. 

StringDefs (StringsA, StringsB) String Package 

A utihty package for copying, comparing, and converting strings and substrings. 

SystemDefs (FSP, Segments) Storage Management 

Provides a simplified interface to the segment and free storage package for allocating and releasing 
temporary storage. 

TimeDefs (TimeConvert) Time Package 

Includes a number of procedures for converting between internal (32 bit GMT), intermediate 
(unpacked record) and external (string) time formats. 

TrapDefs (Resident, Non Resident) Traps 

Defines the runtime implementation of traps generated by the hardware and softw^are. 



3, System Organization 



Mesa systems are available in both standard and basic configurations. The former is intended for 
the day to day operation of most program developers, who do not want to provide a large amount 
of software in order to perform simple tasks. On the other hand, the basic system is intended for 
clients who are building complete applications from the ground up, and wish to replace many of the 
standard facilities with their own versions. Several optional packages are available for augmenting 
the capabilities of the the standard and basic systems in various directions, and we hope that many 
more will be added. 



Standard System 

Except for the optional packages listed below, the standard Mesa system (mesa. image) includes all 
the facilities described in this document. In addition to the interfaces described in the previous 
section, it includes a simple user interface called the Mesa Executive: the commands it accepts are 
described in Section 4. 



Basic System 

The basic system (basicmesa.image) includes the following facilities: runtime support for the 
language: Signaller, Resident, NonResident; modules used to access files on the disk: 
Segments, Files, Swapper, DisklO, DiskKD, BFS, StreamsA, StreamsB, Directory; the 

process package (Process), the string package (StringsA, StringsB), and the free storage 
package (FSP); the loader and its associated modules; a debugger interface; an interrupt key: and a 
nub of the Mesa Executive. The are no facilities for using the display or keyboard in the basic 
system, nor are there any of the modules associated with making image files. These and other 
packages are available as separate configurations (see below). See basicmesa.config for the list of 
exported interfaces. 



Optional Packages 

To assist in tailoring applications built using the basic system, some facilities are optional and 
packaged separately. TTie configurations marked as standard are included in the standard Mesa 
system; the others may be loaded optionally. None of these packages are part of the basic system; 
they must be included in the user's configuration (or otherwise loaded) if they are needed. 

Checkpoint 

Implements check files (Image Files). 

DisplayPackage (standard) 

Implements the display and font procedures. An instance of StreamlO is also included (Display 
Package). 
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ImageMaker (standard) 
Implements image files (Image Files). 

ImageRunner 

Implements image file loading (Image Files). 

UnNewConfig 

Implements unloading of configurations (Modules). 



4. Mesa Executive 



The Mesa Executive serves as the user interface for the standard Mesa system. It provides facihties 
for loading and starting Mesa programs, and for saving the state of a system in an image file; it is 
also the primary interface between your program and tlie Mesa debugger. The Mesa Executive has 
five commands, each identified by their first letter: New, Start, Debug, Makelmage, and Quit. 
The commands are discussed in detail below. 

New [filename] 

Performs a new on the configuration (or module) filename, loading it into the system. If 
no extension is supplied, *'.bcd" is assumed. The global frame of the control module of 
the configuration is returned, but it is not started. If the configuration contains no control 
module, zero is returned. 

Start [frame] 

Performs a start on frame (specified in octal). Note that module parameters can not be 
supplied. Typing ESC in place of frame starts the frame returned by the last New 
command. 

Debug [conf i rm] 

Invokes the Mesa Debugger. Typing tswAT at any point during execution of a Mesa 
program also invokes the Debugger. In addition, tshift-swat attempts to invoke Swat. 

Makelmage [filename] 

Saves the current state of the system (including any programs that have been loaded) on the 
image file filename. If no extension is supplied, ".image" is assumed. The section on 
Image Files contains further details on the Makelmage command. 

Quit [confirm] 

Exits the Mesa environment, cleaning up its state, and returns to the Alto Executive. 
Typing shift-swat at any point during execution also attempts to abort tlie computation 
and return to the Alto Executive. 

Note: on Alto II keyboards, FR5 (lower right key) also functions as a swat key. 

The Mesa Executive keeps a typescript of these commands (and all data sent to the standard output 
stream) on the file mesatypescript; it can be used as a log of your Mesa session. 

Most of the above commands can be specified on the command line used to invoke Mesa (and 
some are valid for BasicMesa, as well). See the Mesa Users Handbook for further details. 



5. System Facilities 

The material which follows is divided into several subsections, each of which describes a more or 
less logically disjoint subset of the system. The subsections are listed below, and follo\\^ this section 
in alphabetical order. The relevant definitions modules, which clients will want to reference, are 
named in parentheses below^ as well as in the subsections which follow. 



Directory Package (Directory Defs) 

Disk Streams Package (St ream Defs) 

Display Package (AltoDisplay, DisplayDefs, FontDefs.StreamDefs) 

File Package (AltoDefs, AltoFileDefs, SegmentDefs) 

Image Files (ImageDef s) 

Keyboard Package (KeyDefs, StreamDefs) 

Miscellaneous (InlineDefs.MlscDefs) 

Modules (FrameDefs) 

Processes and Monitors (Process Defs) 

Segment Package (AllocDefs, SegmentDefs) 

Storage Management (FSPDefs.SystemDefs) 

StreamlO Package (lODefs) 

Streams (St ream Defs) 

String Package (AltoDefs, St ringDefs) 

Time Package (TimeDefs) 

Traps (TrapDefs) 
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The Mesa directory package provides a number of procedures to manipulate the standard Alto 
directory (SysDir) or any file which follows the format of die Alto directory (see Di rectory Defs). 
Currently, these routines do nof support either sub-directories or file version numbers. This section 
depends heavily on the section on Files, and that secuon should be read before this. (See Alto 
Operating System Reference Manual for file structure details.) 

The operations described below come in pairs. The operation containing the word Directory 
operates on the standard Alto directory (SysDir). The other operation of the pair operates on the 
directory specified by the disk stream handle dir. 

The simplest operation provided is to enumerate all of the file entries in the directory: 

EnumerateDirectory: procedure [proc: procedure [pointer to FP, string] 

RETURNS [boolean]]; 

Enumerate: procedure [ 

dir: DiskHandle, proc: procedure [pointer to FP, string] returns [boolean]]; 

Calls proc once for each filename in the directory, passing it pointers to the file's FP and 
name. Processing terminates when proc returns true or the end of the directory is 
reached. 

Fine point: these parameters are local to the enumeration procedure and must be copied if they are to be 
retained after the enumeration completes. 

The following procedures may be of use to programmers implementing features beyond those 
provided by NewFile and DestroyFile. 

DirectoryLookup: procedure [fp: pointer to FP, name: string, create: boolean] 
RETURNS [old: boolean]; 

Lookup: PROCEDURE [ 

dir: DiskHandle, fp: pointer to FP, name: string, create: boolean] 
RETURNS [old: boolean]; 

Looks up name in the directory. If an entry already exists, its file pointer is copied into 
fp and TRUE is returned, otherwise false is returned. In addition, if create is true, the 
file will be created (with one emptv data page), and the new file pointer will be copied into 
fp. 

DirectoryLookupFP: procedure [fp: pointer to FP, name: string] 
returns [old: boolean]; 
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LookupFP: procedure [dir: DiskHandle, fp: pointer to FP, name: string] 

RETURNS [old: boolean]; 

Similar to DirectoryLookup, except that tlie directory is searched for a matching FP. It 
returns true if the file pointer was found. In addition it will supply the filename if name 
is not NIL. 

DirectoryPurge: procedure [fp: pointer to FP, name: string] 
RETURNS [found: boolean]; 

Purge: procedure [dir: DiskHandle, fp: pointer to FP, name: string] 
RETURNS [found: boolean]; 

Removes the entry corresponding to name from the directory (it does not disturb the file 
pages pointed to by the FP, however). If the file is found, its file pointer is copied into fp 
and TRUE is returned, otherwise false is returned. 

DirectoryPurgeFP: procedure [fp: pointer to FP] returns [found: boolean]; 

PurgeFP: procedure [dir: DiskHandle, fp: pointer to FP] returns [found: boolean]; 

Similar to DirectoryPurge, except that the directory is searched for a matching FP. It^ 
returns true if the file pointer was found, deleting the entry in the process. Perhaps it 
should also copy the file's name into a supplied parameter? 
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Alto/Mesa Disk Streams Package 

April 1979 

A disk stream (see StreamDefs) is an array-like representation of a disk file. Parts of the file may 
reside in memory from time to time at the convenience of the stream. Like most arrays, a stream 
has a length] unlike array variables, the length of a stream may be changed by appending to it, and 
the maximum length is very large. Disk streams are created by the procedures: 

NewByteStream, NewWordStreann: procedure [ 
name: string, access: AccessOptions] 
RETURNS [DiskHandle]; 

A FileHandle for the file name is created with the given access and DefaultVersion. It is 
locked and opened, and a byte or word stream is attached to it. If access is Append only, the 
stream is positioned at the end of the file, otherwise at the beginning. If access is 
DefaultAccess, Read is assumed. If a valid FileHandle already exists, a stream may be 
attached to it by calling the procedures: 

CreateByteStream, CreateWordStream: procedure [ 
file: FileHandle, access: AccessOptions] 
returns [DiskHandle]; 

The stream's FileHandle and access may be read directly from the StreamObject (after 
discrimination) using the field names file and read, write, append. 

Disk streams are chained together using the link field in a StreamObject. The head of the list is 
returned by the procedure: 

GetDiskStreamList: procedure returns [DiskHandle]; 

The operations allowed on the stream's length are determined by its access options; these options 
are negotiated with the underlying file system (see the section on Files). The options supported by 
the stream package are: 

Read: the length is a constant. 
Write: the length may decrease. 
Append: the length may increase. 

A disk stream has as part of its state a current index into the array representation of the file. The 
first data item is at index zero, the last at length-1. An invariant of a disk stream is index < = 
length. The current index and length are used in defining the semantics of the standard 
operations on a disk streams. See the section on Streams for more information on these generic 
operations. For a disk stream, s (where i is an item of the appropriate type) they are: 

reset[s] 

Effect: sets the index to zero. 
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get[s] 

If: read and index < length. 

Effect: t <- s[index]; index «- index+1; RETURN[t]. 

putback[s, i] 

Effect: St reamOpe ration error. 

put[s, i] 

If: (write and index < lengtli) OR 
(append and index = length). 
Effect: s[index] <- i; index ^ index+1; length <- MAX[index, length]. 

endof[s] 

Effect: RETURN[index = length]. 
destroy[s] 

Effect: IF -- read and index # then length ^ index (i.e. truncate the file if it is not 
positioned at the beginning). Release the FileHandle if there are no segments attached to 

it. 

Since output to the disk is buffered, there may be items in the stream that have not yet been 
written out. The destroy operation causes these items to be written out before releasing the 
StreamObject. 

Actually, there is a little more to it. Disk streams deliver either byte or word items: in either case, 
the index is always computed in bytes. So the description above is a simplification of what really 
happens. Rather than clutter it up, suffice it to say that when accessing files in word mode, index 
values are always rounded up to word boundaries. 

If it is necessary to truncate a file in the cases not covered by destroy (i.e. read OR index = 0), 
call 

TruncateDiskStream: procedure [stream: StreamHandle]; 

Effect: length <- index; stream. destroy[stream]. 

If it is necessary to assure that all the data in the stream has been written to the disk without 
releasing the StreamObject, call 

CleanupDiskStream: procedure [stream: StreamHandle]; 

In addition to the standard operations, the following disk dependent functions are provided to 
efficiently copy large blocks of words to or from the stream: 

ReadBlock: procedure [stream: StreamHandle, address: pointer, words: cardinal] 
returns [count: cardinal]; 

If: read. 

Effect: count *- MiN[words, length-index]; 
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FOR index in [index. . index + count) do 
addresst <- stream[index]; 
address ^ address + 1 ; 

ENDLOOP. 

WriteBlock: procedure [stream: StreamHandle, address: pointer, words: cardinal] 
RETURNS [count: cardinal]; 

If: (write and index < length) OR 
(append and index = length). 
Effect: count <- if append 
then words 

ELSE MiN[words, length-index]; 
FOR index in [index..index + count) do 
streann[index] <- addresst; 
address <- address + 1; 

ENDLOOP. 

length ♦- MAx[index, length]. 

When using Read Block and WriteBlock, the initial index must be on a word boundary 
(otherwise the St ream Position error results). Note that the returned value may be less than 
words if the stream's access does not allow reading or writing of the whole block (the 
StreamAccess error is never raised by either of these procedures). 

The stream index alluded to above is actually a structure: 

Streamlndex:TYPE = record [ 
page: PageNumber, 
byte: cardinal]; 

The first data byte of a stream is at Streamlndex[0, 0]. The current stream position can be 
determined by calling 

Getlndex: procedure [stream: StreamHandle] returns [Streamlndex]; 

It is quite acceptable to do double precision arithmetic on a Streamlndex (and even single 
precision operations on the individual fields, if you are careful about borrows, carries, and 
overflows). Note, however that a Streamlndex is not compatible with the double precision 
arithmetic of long integers. The paged structure of the index can be restored by invoking 

Normalizelndex: procedure [index: Streamlndex] returns [Streamlndex]; 

It returns an index whose byte field is in the range [CCharsPerPage). An index may be 
modified by calling 

Modifylndex: procedure [index: Streamlndex, change: integer] 
RETURNS [Streamlndex]; 

The current index may be set by calling 
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Setlndex: procedure [stream: StreamHandle, index: Streamir»dex]; 

Note that this may actually extend the file (with unspecified data) if Append access is allowed. To 
determine if this w411 happen, you might first want to call 

FileLength: procedure [stream: StreamHandle] returns [Streamindex]; 

Note that FileLength sets the stream to the end-of-file and returns the length as seen through the 
stream; this may differ from the physical length of the disk file (if, for example, items have been 
appended to the stream but not yet written to the disk). 

You may test for the greater-than relation between two stream indexes by calling the procedures 

GrEquallndex: procedure [11 , 12: Streamindex] returns [boolean]; 

Grindex: procedure [11 , 12: Streamindex] returns [boolean]; 

If a physical disk location is required along with the stream position, a file address (FA) will prove 
useful (see AltoFileDefs); it is similar to a Streamindex with a disk address (DA) tacked on the 
front, except that the page field is one origin (in the Alto file system, page zero is the leader page). 

FA: TYPE = MACHINE dependent RECORD [ 

da: DA, 

page: PageNumber, 

byte: CARDINAL]; 

You may record the current stream position and re-establish it later, in a fashion similar to 
Getlndex and Setlndex, by calling the procedures 

GetFA: procedure [stream: StreamHandle, fa: pointer to FA]; 

JumpToFA: procedure [stream: StreamHandle, fa: pointer to FA]; 

The special thing about JumpToFA is that the disk address in the fa is taken as a hint; if it 
doesn't work out (the page number or file serial number doesn't match the stream's version of 
them), JumpToFA will attempt to find the requested page via the shortest route and correct the fa 
accordingly. This may involve starting over at the beginning of the file. If that fails, 

InvalidFP: signal [fp: pointer to FP]; 

will result, probably indicating that the file has been moved (or worse, deleted!) since the stream 
was attached to it. A call on some directory searching procedure may prove useful in this situation, 
to determine if retrying the operation (with a new fp) is appropriate. 
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The Mesa Display Package provides a simple. Teletype style interface to the Alto display (see 
AltoDisplay). There is provision for using any available font: however the display is restricted to 
a single font for any particular incarnation. The font operations (described at the end of this 
document) are independent of the display implementation and may be used by any other display 
package. The package will optionally maintain a typescript of displayed output. 

Display Stream 

Normal access to the display is through a stream interface (see the section on Streams). There is no 
provision for multiple display streams. The module SystemDisplay implements the following 
procedures defined in StreamDefs: 

GetDefaultDisplayStream: procedure returns [DisplayHandle]; 

The interpretation of the basic stream operations is: 

reset clears the display and resets the typescript. 

put displays the character at the next sequential location. 

get, putback and destroy signal StreamError[StreamAccess]. 

endof returns false. 

In addition, the following operations are defined for display streams: 

clearCurrentLine: procedure [stream: StreannHandle] clears the current line of 

the display. The next character will be displayed at the left margin. The typescript 

is repositioned to the beginning of the line. 
clearLine: procedure [stream: StreamHandle, line: cardinal] clears line on the 

the display. The next character will be displayed at the left margin of that line. 

The typescript is repositioned to the beginning of the line. In the current 

Alto/Mesa implementation, clearLine is a no-op. 
clearDlsplayChar: procedure [stream: StreamHandle, char: character] erases 

the last character written on the display. The character must be supplied since the 

stream retains no knowledge of what characters are displayed (the typescript is 

optional). 

DisplayDefs defines some additional interface procedures: 

InitDisplay: procedure [ 

dummySize, textLines, nPages: cardinal, f: FontDefs.FontHandle]; 

This procedure initializes the display with dummySize blank scan lines at the top and 
room for at most textLines lines of text using n Pages pages of memory for data 
structures and bitmap. The number of text lines and the display width are reduced if 
necessary to make everything fit in n Pages. 

FinePoini: the amount of memon- necessan' to guarantee that n full width lines of text can be displayed is 
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n*(4-rh*w) words, where h is the height of the font in scan Hnes (rounded up to an even number) and w is 
the width of the display in words. 

SetSystemDisplaySize: procedure [nTextLines, nPages: cardinal]; 

Clears the display and reinitializes it with tlie new parameters. 

SetSystemDisplayWidth: procedure [indent, width: cardinal]; 

Clears the display and reinitializes it with the new width parameters, indent is the number 
of bits from the left edge of the screen to the first display position and width is the width 
of a display line in bits. (The actual width will be the nearest multiple of 32 bits.). 

FinePoint: indenting by multiples of 16 bits is very efficient. 

SetDummyDlsplaySize: procedure [nScanLines: cardinal]; 

Changes the size of the blank space at the top of the display. The space will be rounded 
up to an even number of scan lines and may be zero. 

Background: TYPE = {white, black}; 

DisplayOff: procedure [color: Background]; 

DisplayOn: procedure; 

DisplayOff releases all of the space allocated to the display and swaps out the font. All of 
the parameters of the display are saved so that DisplayOn can restore the previous state 
(but not the contents) of the display. 

StartCursor: procedure; 

StopCursor: PROCEDURE; 

StartCursor forks a process in DisplayControl that blinks the cursor. If the cursor 
process is already running, it is a no op. StopCursor stops it. 

BlinkCursor: procedure returns [boolean]; 

Blinks a "cursor" at the position where the next character will be displayed. Each call 
changes the state of the cursor from "on" to "off* or vice versa. BlinkCursor returns 
TRUE if the last call changed the cursor state to on. The cursor is always turned off before 
a character is displayed or erased. 

SetlypeScript: procedure [StreamDefs.DiskHandle]; 

This procedure establishes a disk stream as a typescript for the display. Passing nil will 
disable the typescript. Characters sent to the display stream while the display is off will 
appear in the typescript. The typescript must be an open byte stream with 
Read + W rite + Append access. 

GetlypeScript: procedure returns [StreannDefs.DiskHandle]; 

This procedure returns the disk stream that is behind the typescript for the display. 
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DisplayControl: program; 



This is the control module used in Mesa.image. It will initialize the display, font and 
typescript (using either MesaFont.al or SysFont.al and Mesa.Typescript) and start a process 
to call BlinkCursor at half second intervals. It will also reestablish the display (including 
font and typescript) after a Makelmage or MakeCheckPoint. 



Fonts 

A FontObject provides a simple object style interface to character fonts. Operations are provided 
for painting or erasing characters from the font in a bitmap. Font Dels defines the following 
TYPES and procedures; 

BitmapState:TYPE = record [ 
origin: pointer, 
wordsPerLine, x, y: [0..77777B)]; 

A BitmapState describes where a character will be placed within a bitmap, origin is a 
pointer to the beginning of the bitmap. . wordsPerLine is the horizontal width of the 
bitmap (it must be even if the bitmap is to be displayed), x and y are measured from the 
upper left corner in bits right and scan lines down respectively. 

FontHandle:TYPE = pointer to FontObject; 

FontObject; TYPE = RECORD [ 

paintChar: procedure [FontHandle, character, pointer to BitmapState], 
clearChar: procedure [FontHandle, character, pointer to BitmapState], 
charWidth: procedure [FontHandle, character] returns [cardinal], 
charHeight: procedure [FontHandle, character] returns [cardinal], 
close: procedure [FontHandle], 
destroy: procedure [FontHandle], 
lock: procedure [FontHandle] returns [pointer], 
unlock: procedure [FontHandle]]; 

A FontObject implements the following operations: 

paintChar: ORs the specified character from the font into the bitmap position specified in 
the BitmapState; x is updated to point to the next character position. There is no bounds 
checking. 

ClearChar: erases the bit rectangle which bounds the character. The input state points 
just beyond the character and is modified to point to where the character used to be. 
paintChar[f, c, s] followed by clearChar[f, c, s] leaves s unchanged. 

CharWidth, charHeight; return the width and height of a character in bits and scan lines 
respecdvely. 

close: swaps the font out of memory if it is not otherwise in use. The font wall always be 
swapped in when needed. It is not generally locked. 

destroy: calls close and then releases the space allocated for the FontObject. The font 
segment is not deleted. 
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lock: locks the font segment in memory and returns a pointer to the first word. This can 
be used to implement otlier operations on the bits in the font. Note that nothing in a 
FontObject dictates what font fonnat is used. 

unlock: unlocks the font after a call to lock. 
CharWidth: procedure [font: FontHandle, char: character] returns [cardinal]; 

Equivalent to font.charWidth[font, char]. 
CharHeight: procedure [font: FontHandle, char: character] returns [cardinal]; 

Equivalent to font.charHelght[font, char]. 

CreateFont: procedure [SegmentDefs.FileSegmentHandle] returns [FontHandle]; 

Allocates space (from the system heap) for a FontObject and initializes its operations to 
use the font in the supplied segment. 

GetFont: procedure returns [FontHandle]; 

Returns the FontHandle for the system font. 

The module AlFont implements FontObjects for "Al" format fonts. Modules for other font 
formats can be substituted easily. At this time no other modules have been written or planned. 

Mesa.image uses SystemDIsplay, AlFont, and DIsplayControl for its default display. They 
are also available as a separate package in Display Package for users of BasicMesa. 
Display Package also contains an instance of StreamlO. 
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Logically, the Mesa file package is a sub-module of the segmentation machinery, but it is described 
separately because other objects (e.g. disk streams) also use this interface. Internally, the file 
machinery maintains a set of items called FileObjects: a file object, among other things, contains 
the file's disk address and serial number, as well as its access rights, several reference counts, and an 
optional file length hint. 

The Mesa system follows most conventions of the Alto file system (although some, including 
multiple versions and sub-directories are not currently supported.) See the Alto Operaiing System 
Reference Manual document for a description of the Alto file system. A description of the various 
procedures used to manipulate the Alto's directory appears in the section on Directories. 



Files 

A file is an integral number of pages which logically appear to be contiguous, irrespective of their 
physical location. The pages of a file are numbered from zero up to some maximum (see 
AltoDefs): 

MaxFilePage: cardinal; - maximum file page number 

PageNumber: type = [0., MaxFilePage]; 

In the Alto file system, page zero of the file (the leader page) is special; it contains file status 
information. Thus the data actually begins at page one. 

Externally, a file is known by its name, which is just a string. Internally, Mesa retains only a file's 
FP, which is an abbreviated form of the Alto file system's file pointer (see AltoFileDefs): 

FP: TYPE = RECORD [ 

serial: SN, -- internal file serial number 

leaderDA: vDA]; - first virtual disk address 

The correspondence between file names and FPs is maintained in the file system's directory 
(SysDir). After the file is initially looked up, the name is discarded; the Mesa world deals only in 
FPs thereafter. A directory search is required if the name must be recovered. 



File Objects 

A FileHandle is used to refer to a file in the Mesa environment, and can be obtained by a call on 
NewFile (described bedow); it is simply a pointer to a record called a FileObject (see 
SegmentDefs). 
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FileHandle: type = pointer to FileObject; 

FileObject; type = record [ 

open: boolean, - // the file is open 
read, write, append: boolean, - access rights 

lock: [O..MaxLocks], - reference count 

segcount: [O..MaxSegs], - attached segments 
swapcount: [O..MaxRefs], - swapped in segments 

. . . ]; - plus Other private fields 

The following options are used when creating new file objects: 

AccessOptlons: type = [0.,7]; 
Read: AccessOptions = 1; 
Write: AccessOptions = 2; 
Append: AccessOptions = 4; 

VersionOptions: type = [0..3]; 

NewFileOnly: VersionOptions = 1 ; 
OldFileOnly: VersionOptions = 2; 

Read access allows existing pages of the file to be read; Write means that existing pages can be' 
written (or deleted; perhaps a separate Delete option should be included). Append allows new 
pages to be added to the end of the file (files do not have holes in them). 

Fine point: Append does not imply Write access. Append means that new pages may be added to the file but 
existing pages may not be modified. 

Disallowed combinations are {NewFileOnly, OldFileOnly} and {NewFileOnly, -Append}. If 
Append access is not specified, OldFileOnly is assumed. If you like, you may specify 
DefaultAccess, which is equivalent to Read. (Note that Append access must be specified in 
order to create the file.) 

Fine point: if DefaultVersion is specified, the file is created if it did not previously exist. 



Signals 

Signals associated with FileObjects are as follows: 

FileNameError: signal [name: string]; 

The file name is invalid, or the file does not exist (OldFileOnly), or tlie file does exist 
(NewFileOnly). 

FileAccessError: signal [file: FileHandle]; 

An attempt to perform some operation not allowed by the current access, or the requested 
access and version options are inconsistent (see the disallowed combinations above). 
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InvalidFP: signal [fp: pointer to FP]; 

A file positioning operation has determined that the file serial number in the FP of the file 
object does not match the disk label. Most likely, the FileHandle references a file which 
has been moved or destroyed (or clobbered) since it was last referenced 

FileError: signal [file: FileHandle]; - all other file errors 



File Creation/Deletion 

A FileObject is created using the following procedures: 

NewFile: PROCEDURE [ 

name: string, access: AccessOptions, version: VersionOptions] 
RETURNS [FileHandle]; 

Given a file name and access rights, this procedure creates a new file object and returns a 
pointer to it. A check is made that the file exists in the directory, creating it if necessary, 
but the file is not opened as a result of this call. Objects attached to the file (segments and 
streams, for example) ensure that the file is open before attempting a transfer. If there is 
already a file object for the file specified, its access is updated (by or'ing; this is not a 
protection system), and a pointer to the existing object is returned. 

InsertFile: procedure [fp: pointer to FP, access: AccessOptions] 
RETURNS [FileHandle]; 

Creates a file object directly from fp, without searching the directory. If there is already a 
file object with a matching fp, its access is updated (by or'ing; this is not a protection 
system), and a pointer to the existing object is returned. 

Internally, Mesa keeps track of the number of segments attached to each file (segcount) and of 
those the number which are currently swapped in (swapcount). When the swapcount goes to 
zero, the file may be closed, and when the segcount goes to zero, the file object is released (only 
the latter operation happens automatically). Since a file may have other objects attached to it 
(streams, for example), it may be necessary to prevent the file object from being released even when 
there are no more segments attached to it. The lock field serves this purpose, and is manipulated 
by the procedures 

LockFile, UnlockFile: procedure [file: FileHandle]; 

A maximum of MaxLocks locks may be performed on each file object. Note that a file object is 
«o/ automatically released when its lock count goes to zero. 

A FileObject is released by 

ReleaseFile: procedure [file: FileHandle]; 

The file is first closed if it is open; then its file object is released. A FileError will be 
generated if there are segments associated with the file at the time of this call. Note: except 
for this error check, releasing a file which is locked is a no-op. 

A file is physically destroyed by calling 
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DestroyFile: procedure [file: FlleHandle]; 

In addition to releasing the file object, the file's pages are deleted and its entry is removed 
from the directory. The file object must not have any segments currently attached to it, nor 
may it be locked; either condition results in a FileError. 

To be on the safe side, destroying a file is somewhat complicated if it currently has segments 
attached to it. The file must first be locked, then all of its segments deleted and all streams 
attached to it destroyed, then the file should be unlocked and finally DestroyFile should be 
called. This sequence assumes that no other client has a lock on the file. 



File Properties 

Characteristics of the disk file associated with a FileObject are obtained and changed using the 
following procedures: 

FindFlle: procedure [fp: pointer to FP] returns [FileHandle]; 

Searches all existing file objects for one whose serial number and disk address match those 
contained in fp. Returns nil if no match can be found. 

GetFileFP: procedure [file: FlleHandle, fp: pointer to FP]; 

Copies the file pointer from file into fp. 

GetFileAccess: procedure [file: FileHandle] returns [access: AccessOptions]; 

Converts the read, write, and append bits of a file object into a form that can be passed 
to NewFlle. 

Set File Access: procedure [file: FileHandle, access: AccessOptions]; 

Ofs access into the file object (this is not a protection system). 

File lengths hints are no longer contained in every FileObject. A separate object contains the 
length for a file. This separate length object is not required and is allocated only when operations 
on file lengths are invoked (see SegmentDefs). Operations on file lengths are: 

GetEndOfFile: procedure [file: FlleHandle] 

RETURNS [page: PageNumber, byte: cardinal]; 

Returns the page number of the last page in the file that contains data, together with the 
number of bytes in that page (the number of the first non-existent byte in the page, 
counting from zero). In the Alto file system, page zero is the leader page, the first data 
page being page one. Note that if the last data page is full, a null page is appended to the 
file, but GetEndOfFile does not tell you about it (so do not count on it being there). For 
an empty file, this routine returns [0, BytesPerPage] (reflecting the existence of the 
leader page). 

GetEndOfFile first opens the file (if it is closed) to obtain the length hint from the leader page. It 
also inserts the current file length into the file length object (creating one if necessary), so that 
subsequent requests for the length will not require reading the disk. 
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SetEndOfFile: procedure [file: FileHandle, page: PageNumber, byte: cardinal]; 

Extends or tmncates the file as necessary to make page the number of its last data page, 
with byte bytes in it. The arguments are first adjusted to include a null page if byte = 
BytesPerPage. Extending requires Append access, truncating requires Write access. 



Miscellaneous 

The procedure EnumerateFiles is provided so that one may conveniently scan all file objects that 
currently exist. 

EnumerateFiles: procedure [proc: procedure [FileHandle] returns [boolean]] 
returns [file: FileHandle]; 

This procedure calls proc once for each file object that is currently exists. This process 
will terminate when the list of file objects is exhausted or when proc returns true. In the 
latter case, the FileHandle of the last FileObject processed is returned. Otherwise, nil is 
returned. 

If new file objects are created while EnumerateFiles is in control, it is not guaranteed that they 
will be included in the sequence of FileHandles passed to proc. 
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A Mesa image file contains the information necessary to start execution of a Mesa system. In 
addition to image files that contain all code and data, there are also image files, called check files. 
that contain only data. (Check files know the addresses of other files on the disk and therefore 
cannot be moved like other image files). This section defines the facilities provided to make them. 
See ImageDefs for further details. 



Making Image Files 

The standard system contains code to make an image file of itself and any user programs which 
have been loaded. Clients may make an image file by calling the procedure: 

Makelmage: procedure [nanne: string]; 

Make an image file on file name. Returns to Alto Executive. When the image file is 
restarted, Makelmage returns to its caller 

Clients may also make an image file by invoking the Mesa Executive's Makelmage command. It 
accepts a filename, defaults the extension to ".image'* and calls Makelmage [name]. When the 
image file is restarted, the Mesa Executive will be ready to accept a new command. 

Makelmage normally merges all the BCDs that have been loaded into one bed, and cleans up 
system data structures. This results in faster loading of additional BCDs into the new^ image. 

Those clients that do not want BCDs merged during a Makelmage because they call 
UnNewConfig may use the following procedure: 

MakeUnMergedlmage: procedure [name: string]; 

Signals that may be generated by Makelmage or MakeUnMergedlmage are: 

Invalidlmage: signal; 

An attempt has been made to make an image file on top of the currently excuteine image 
file. 

NoRoomlnlmageMap: signal; 

The map in the ImageHeader has filled up. This usually means that there are too many 
segments in memory at the time the image file is made. 
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Check Files 

Check files differ from normal image files in that they do not contain all the code and data to start 
the execution of the image file. Check files only contain the data of the Mesa system, and all code 
and other segments remain in their original files. As a result, check files are made and restarted 
very quickly. However, care must be taken not to destroy files that are pointed to by the check file. 
Check files are useful for making check points in the execution of a Mesa system. The procedures 
and signals that make check files are: 

MakeCheckPoint: procedure [name: string] returns [restart: boolean]; 

Makes a check file on file name. Returns to caller when finished as if nothing happened 
with restart false. If the check file is being restarted, it returns to the caller with true. 

NoRoomlnCheckMap: signal; 

In MakeCheckPoint, the map in the ImageHeader has filled up. This usually means 
that there are too many segments in memory at the time the check file is made. 

The ability to, make check files is not included in the basic system. Clients should include the 
Checkpoint module in their configuration. 



Running Image Files 

Mesa programs may run another image file without returning to tlie Alto Executive. The 
procedures and signals that implement this are: 

Runlmage: procedure [file: SegmentDefs.FileSegmentHandle]; 

Runs the image file specified by file where file is a segment handle for the header of the 
image file. The current state of the present image file is lost, and the new image file is 
loaded and started. 

Fine point: currently the header of an image file is page one (this may change in the future, and may not be 
constant). Communication between the two image files must be done via disk files (like Com.cm). See the 
Alto Operating System Reference Manual. 

tnvalidimage: signal; 

In Runlmage, file specifies an invalid image file. 

NoRoomForLoader: signal; 

In Runlmage, there is no room for the bootstrap loader that loads and starts the image 
file. 

Clients should include the configuration ImageRunner in their configuration. 
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Miscellaneous 

The version stamp of the currently running image file may be obtained by calling the procedure: 
ImageVersion: procedure returns [BcdDefs.VersionStamp]; 

The time that the currently running image file was created may be obtained by calling the 
procedure: 

ImageTime: procedure returns [TimeDefs.PackedTime]; 
The same information can be obtained about the caller s bcd from the procedures: 
BcdVersion: procedure returns [BcdDefs.VersionStamp]; 
BcdJime: procedure returns [TimeDefs.PackedTime]; 

A client may stop execution of a Mesa system and return to the Alto Executive by calling: 
StopMesa: procedure; 

A client may terminate execution of a Mesa system as if shift-swat had been typed and return to the 
Alto Executive by calling: 

AbortMesa: procedure; 



Cleanup Procedures 

Client programs sometimes need to be notified when certain events occur so they can perform 
various cleanup functions. Cleanup procedures provide a facility to notify client programs when 
image files are made or restarted, and when stopping execution of Mesa programs. The types and 
data structures involved with Cleanup procedures are: 

CleanupProcedure: type = procedure [why: CleanupReason]; 

Cleanupltem: type = record [ 
link: pointer to Cleanupltem, 
mask: cardinal, 
proc: CleanupProcedure]; 

CleanupReason: type = NovaOps. CleanupReason; 

NovaOps. CleanupReason: type = { 

Finish, . . . Save, Restore, Checkpoint, Restart, Continue, . . .}; 

CleanupReasons are copied from NovaOps. Vahd ones are: 

Finish -- StopMesa was called. 

Save -- Makelmage was called. 

Restore •- returning from Makelmage. 

Checkpoint - Checkpoint was called. 

Restart •• returning from Checkpoint restarted by the Alto Executive. 

Continue -■ returning from Checkpoint. 



Alto/Mesa Image F'iles 27 

The following procedures may be used to add or remove a cleanup procedure. The list of 
Cleanupltems is processed in the opposite order when returning from an image file than when 
making one. 

AddCleanupProcedure: procedure [pointer to Cleanupltem]; 

RemoveCleanupProcedure: procedure [pointer to Cleanupltem]; 

Warning: these procedures may not be invoked from inside Cleanup procedures. 

CleanupMask: array CleanupReason of cardinal = 

[1, 2, 4, 10B, 20B, 40B, 1008, 2008, 4008, 10008]; 

When the Cleanup procedure mechanism is invoked, each item is examined. If the bit 
corresponding to the reason is set in item. mask, item. p roc is called. Clients must set the mask 
field so that their procedure is invoked only for the reasons they expect. For example, if a client 
needed to be notified when a normal image file was being made or started, the mask would be set 
to: 

CleanupMask[Save] + CleanupMask[Restore]. 

Warning: if the item. mask is improperly set, item.proc may be invoked at sensitive times, 
probably resulting in erroneous behavior. 

Makelmage Restrictions 

1. The name of the new image file may not be the same as the name of the image file running 
at the time Makelmage is called. An image file can be renamed any time it is not running. 

2. The user program should not have handles on any files or disk streams. Any file segments 
allocated by a user program will be made a part of the new image file. 

3. This list of restrictions may not be exhaustive. In general you should avoid doing anything 
other than loading modules and initializing data structures before making an image file. 

MakeCheckPoint Restrictions 

1. The name of the new image file may be die same as the name of the image file running at 
the time MakeCheckPoint is called, only if the current image file is a check file. A check file 
should not be renamed. 

2. The files that are pointed to by the check files should not be moved or altered. Care must be 
taken with open disk streams that the pages of \he current position of the stream are not moved or 
destroyed. 

3. This list of restrictions may not be exhaustive and care must be taken with all files that are 
open at the time the check file was make. 
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CleanupProcedure Restrictions 

1. CleanupProcedures are called with intermpts and timeouts turned off. 

2. This list of restrictions may not be exhaustive and care must be taken when using 
CleanupProcedures. 
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The Keyboard package consists of the modules KeySt reams and Keyboard and provides a 
Teletype style interface to the undecoded keyboard through a device independent stream interface. 
Multiple, independent keyboard streams are supported. A default keyboard stream is created at 
initialization time. (See the section on StreamlO for higher level operations.) The Keyboard 
Package also optionally causes the hardware cursor to track the mouse. A single keyboard process 
runs at interrupt level approximately 60 times per second to sample the keyboard hardware. 

The following procedures and types are defined in StreamDefs. 

KeyboardHandle:TYPE = pointer to Keyboard StreamObject; 

The standard operations on a keyboard stream are: 

reset[s] clears the buffer associated with s; any characters in the buffer are lost. 
get[s] returns the next character in the buffer; if endof[s] is true, waits until it is 

FALSE. 

putback[s,i] modifies the stream so that the next get[s] will return i, independent of 
any type-ahead. If the buffer is full, putback is a no-op (sorry about that). 

put[s,i] produces a StreamAccess error. 

endof[s] true if there are no characters in the buffer. 

destroy[s] destroys s in an orderly way, freeing the space it occupies. Any characters in 
the buffer at the time of the destroy are lost. If s is the current keystream, the 
StreamOperation error results. 

CreateKeyStream: procedure returns [KeyboardHandle]; 

Creates a new keyboard streams. Any number of streams may be created. Each stream has 
its own buffer for type ahead. (Space for the StreannObject is allocated from the system 
heap.) 

GetDefaultKey: procedure returns [KeyboardHandle]; 

Returns the default stream (created at initialization time). 
GetCurrentKey: procedure returns [KeyboardHandle]; 

Returns the current stream. Initially the default keyboard stream is current. 
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OpenKeyStream: procedure [stream: StreamHandle]; 

Makes stream the current keyboard stream.The stream which was current before the call 
is undisturbed, except that input characters are no longer directed to it by the keyboard 
process, but to stream instead. 

CloseKeyStream: procedure [stream: StreamHandle]; 

Makes the default keyboard stream current. Characters already typed remain in stream's 
buffer. The StreamOperation error results if stream is not the current stream. 

CursorTrack: procedure [boolean]; 

Calling this procedure with true enables cursor tracking; false disables it. When tracking 
is enabled, the mouse coordinates are copied to the cursor coordinates each time the 
keyboard process runs. 



Low Level Access 



The basic system does not provide access to the keyset or mouse through the stream. Definitions 
are provided for clients wishing to access the bits of the keyboard directly or to change the 
interpretation of any of the keys. The module KeyDefs defines types and procedures for lower 
level access to the keyboard hardware. 

updown:TYPE = {down, up}; 

KeyBits:TYPE = machine dependent record [ 
blank: [0..377B], -- not used 

Keysetl, Keyset2, Keysets, Keyset4, Keysets: updown, 
Red, Blue, Yellow: updown, 
Five, Four, Six, E, Seven, D, U, V, 
Zero, K, Dash, P, Slash, BackSlash, LF, BS: updown. 
Three, Two, W, Q, S, A, Nine, I, 

X, O, L, Comma, Quote, RightBracket, Spare2, Sparel : updown, 
One,ESC,TAB, F,Ctrl,C, J,B, 

Z, LeftShift, Period, SemiColon, Return, Arrow, DEL, FL3: updown, 
R,T, G,Y,H, Eight, N,M, 
Lock, Space, LeftBracket, Equal, RightShift, SpareS, FL4, FR5: updown]; 

Keys: pointer to KeyBits = •• magic memory location -■ ; 

MouseButton:TYPE = {RedVellowBlue, RedBlue, RedYellow, Red, BlueYellow, Blue, 
Yellow, None}; 

MOUSeBitS:TYPE = machine dependent RECORD [ 

blank: [0..377B], -■ Diablo, Versatec, etc. 

keyset: [0.. 37b], -O => down, i.e. normal state is 37b 

buttons: MouseButton]; 
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Mouse: POiNTERTO MouseBits = ■- magic memory location -- ; 

KeyName:TYPE = { 

. . . , -• unused values 

Keysetl, Keyset2, Keysets, Keyset4, Keysets, 

Red, Blue, Yellow, 

Five, Four, Six, E, Seven, D, U, V, 

Zero, K, Dash, P, Slash, BackSlash, LF, BS, 

Three, Two, W, Q, S, A, Nine, I, 

X, 0, L, Comma, Quote, RightBracket, Spare2, Sparel, 

One, ESC, TAB, F, Ctrl, C, J, B, 

Z, LeftShlft, Period, Semicolon, Return, Arrow, DEL, FL3, 

R,T, G,Y,H, Eight, N,M, 

Lock, Space, LeftBracket, Equal, RightShift, SpareS, FL4, FR5}; 

Alto II names for some keys are different. 

FL1: KeyName = DEL; 
FL2: KeyName = LF; 
BW: KeyName = Sparel; 
FR1: KeyName = SpareS; 
FR2: KeyName = BackSlash; 
FR3: KeyName = Arrow; 
FR4: KeyName = Spare2; 

KeyltemiTYPE = record [ 
Letter: boolean, 
ShiftCode:[0..177B], 
NormalCode: [0..377B]]; 

There is a Keyltem for every key (including mouse and keyset keys). A NormalCode = 
causes the key to be ignored; a ShiftCode = puts in a zero for the key when the 
shift key is down; Letter means that the ShiftCode is selected by the shift lock key. 
Note that the ShiftCode is 7 bits and the NormalCode is 8 bits. 

ChangeKey: procedure [key: KeyName, action: Keyltem] 
RETURNS [oldAction: Keyltem]; 

This procedure changes the meaning of a key and returns the old value. 

Initialization 

BasicMesa does not contain a keyboard package. Clients of BasicMesa who do not wish to supply 
their own keyboard procedures should include Keyboard and KeySt reams in their 
configurations. The following additional definitions from KeyDefs are needed: 

Keyboard: program; 

KeyStreams: program; 
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In order to initialize the keyboard process, a client must include these statements: 

FrameDefs.MakeCodeResident[FranneDefs.GlobalFrame[KeyDefs. Key board]]; 
START KeyDefs.KeySt reams; 
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This section describes some miscellaneous facilities in Alto/Mesa. 

MiscDefs 
Zero: procedure [p: pointer, I: cardinal]; 
FOR i IN [0..I) DO (p + i)t ♦- 0. 
SetBlock: procedure [p: pointer, v: unspecified, I: cardinal]; 

FOR i in [0..I) DO (p + i)t ^ V. 

DAYTIME: PROCEDURE RETURNS [AltoFileDefs.TIME]; 

Returns the current time in the format maintained by the Alto Operating System and 
recorded in Alto files. This is not the same format as a TimeDefs.PackedTime. 

CurrentTime: procedure returns [long cardinal]; 

Returns the current time. This is the same format as a TimeDefs.PackedTime. 

GetNetworkNumber: procedure returns [cardinal]; 

Returns the number of the network to which the Alto is connected or if there is no 
network or no response from a gateway. 

Fine point: this procedure is used by the Compiler and others to generate unique identifiers for output files. 

CommandLineCFA: procedure returns [pointer to AltoFileDefs.CFA]; 

Returns a pointer to the CFA for the point at which the Mesa executive stopped reading 
the command line (com.cm). This is valid only when a configuration is started from the 
command line using Mesa.image or BasicMesa.image. The caller can use the CFA to 
quickly open a stream on the command line and read any additional commands. The CFA 
should be updated before returning to the Mesa executive. See the sections on Files and 
Streams for more information. 

CallDebugger: procedure [string]; 

WorryCallDebugger: procedure [string]; 

These procedures invoke the Debugger without tlie overhead of raising an uncaught signal. 
The Debugger will display the parameter if it is not nil. The worry call will invoke the 
Debugger in worry mode. 
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InlineDefs 
COPY: PROCEDURE [from: pointer, nwords: cardinal, to: pointer]; 

FOR i in [0.. nwords) do (to + i)t <- (from + i)t. 
DIVMOD: procedure [num, den: cardinal] returns [quotient, remainder: cardinal]; 

Returns both the quotient and remainder of the unsigned division of num by den. 

LDIVMOD: PROCEDURE [numlow: word, numhigh: cardinal, den: cardinal] 
returns [quotient, remainder: cardinal]; 

Like DIVMOD except that the numerator is the double length unsigned number 
numhigh*2*'^ + numlow. Results are undefined if the quotient is greater than 2^^-l. 

LongNumber: TYPE = machine dependent record [ 
select overlaid * from 

Ic =>[lc: long cardinal], 
li =>[li: LONG integer], 

tu =>[lu: LONG unspecified], 

num = > [lowbits, highbits: cardinal], 
endcase]; 

The LongNumber structure permits access to the high and low words of long cardinals 
and LONG integers. Alternately, the following procedures may be used: 

LowHalf: procedure [long unspecified] returns [unspecified]; 

HighHalf: PROCEDURE [long unspecified] returns [unspecified]; 

LowHalf and HighHalf allow access to the machine dependent components of long 
CARDINALS, LONG INTEGERS and LONG POINTERS. LowHalf retums the least significant word, 
while HighHalf returns the most significant word. 

LowByte: PROCEDURE [unspecified] RETURNS [UNSPECIFIED]; 

HighByte: procedure [unspecified] returns [unspecified]; 

LowByte and HighByte return the least significant and most significant byte of a word 
respectively. 

LongMuit: procedure [cardinal, cardinal] returns [product: long cardinal]; 

Returns the double precision result of the unsigned multiplication of the two single 
precision arguments. 

LongDIv: procedure [num: long cardinal, den: cardinal] returns [cardinal]; 

Returns the result of the unsigned division of num by den. The result is undefined if the 
quotient is greater than 2-^^-1. 
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LongDivMod: procedure [num: long cardinal, den: cardinal] 
RETURNS [quotient, remainder: cardinal]; 

Like LongDIv except both quotient and remainder are returned. 

BITAND, BITOR, BITXOR: PROCEDURE [UNSPECIFIED, UNSPECIFIED] RETURNS [UNSPECIFIED]; 

These functions compute the bitwise and, or, or XOR of their arguments. 

BITNOT: PROCEDURE [UNSPECIFIED] RETURNS [UNSPECIFIED]; 

Returns the ones complement of the input. 

BITSHIFT: PROCEDURE [value: unspecified, count: integer] returns [unspecified]; 

Returns value shifted by ABS[count] bits. The shift is left if count > 0, right if count 
< 0. 

Floating Point 

While the Mesa system does not provide any support for floating point operations, the Compiler 
does recognize type real and generates calls to client supplied procedures via the system data 
vector (SD). The definitions of SD and all indices into SD are in SDDefs. In the following 
description the notation 

SD[index]: procedure . . . 

means that the client should declare a procedure P of the correct type and assign its descriptor to 
the appropriate element of SD (SD[lndex] <- P). The Compiler makes no assumptions about the 
representation of reals except that they occupy two words. 

SD[SFADD]: PROCEDURE [a, b: REAL] RETURNS [REAL]; 

Called to perform addition. 
SD[sFSUB]: PROCEDURE [a, b: real] returns [real]; 

Called to perform subtraction. 
SD[sFMUL]: procedure [a, b: real] returns [real]; 

Called to perform multiplication. 
SD[sFDIV]: PROCEDURE [a, b: real] returns [real]; 

Called to perform division (a/b). 
SD[sFCOMP]: PROCEDURE [a, b: real] returns [integer]; 

Called to compare reals. Return -1 if a<b, if a = b, 1 if a>b. 
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SD[sFLOAT]: PROCEDURE [LONG INTEGER] RETURNS [REAL]; 

Called to convert fixed point to floating point. 

SD[sFIX]: PROCEDURE [real] RETURNS [LONG INTEGER]; 

The Compiler does not generate calls to this procedure. It is included for completeness. 

DoubleDefs 

The following procedures from DoubleDefs have been retained for compatibility. They are no 
longer supported and clients should now use long cardinals. (DAdd, DSub, and DCompare 
are inline procedures and are available to any Mesa program. The others are available only to 
clients which include Double in their configuration.) 

DAdd: PROCEDURE [a,b: long cardinal] returns [long cardinal]; 

Returns the double precision unsigned sum of a and b.. 
DSub: procedure [a,b: long cardinal] returns [long cardinal]; 

Returns the double precision unsigned difference of a and b. 
Comparison: type = {less, equal, greater}; 
DCompare: procedure [a,b: long cardinal] returns [Comparison]; 

Returns less if a<b, equal if a = b. greater if a>b. 
DMultiply: PROCEDURE [a,b: long cardinal] returns [product: long cardinal]; 

Returns the product of the unsigned multiplication of a by b. 

DDivide: procedure [num, den: long cardinal] 
returns [quotient, remainder: long cardinal]; 

Returns the quotient and remainder of the unsigned division of num by den. 

DNeg: procedure [a: long cardinal] returns [long cardinal]; 

While somewhat a contradiction in tenns, this procedure negates a long cardinal by 
performing DSub[0, a]. 

Dine: procedure [a: long cardinal] returns [long cardinal]; 

DAdd[1, a]. 
AppendDouble: procedure [s: string, a: long cardinal]; 

The value of a is converted to text in decimal and appended to s. 
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This section documents the operations required to manipulate modules at a more detailed level than 
provided by the language. It is intended for experienced programmers who have a genuine need to 
manipulate low level system structures. See Frame Defs for further details. 



Global Frames 

A GlobalFrame is the implementation of the program language construct. All manipulation of 
GlobalFrames is done using GlobalFrameHandles. 

GlobalFrameHandle: type = pointer to GlobalFrame; 

GlobalFrame: type = record [. . .]; 

The procedures which manipulate global frames are: 

GlobalFrame: procedure [link: unspecified] returns [GlobalFrameHandle]; 

Returns the GlobalFrameHandle corresponding to link, which is interpreted as a control 
link; it should be either a procedure, pointer to frame or program. If link is not a 
vahd control link, then either the signal InvalidGlobalFrame or UnboundProcedure 
will be raised (see the section on Traps for a description of UnboundProcedure). 

ValidateGlobalFrame: procedure [GlobalFrameHandle]; 

Checks to see that the parameter is a valid global frame; InvalidGlobalFrame is raised 
if not. Used to check the validity of GlobalFrameHandle parameters by system 
procedures such as GlobalFrame. 

InvalidGlobalFrame: signal [frame: GlobalFrameHandle]; 

Indicates that frame does not point to a valid global frame. 

EnumerateGlobalFrames: procedure [ 

proc: procedure [GlobalFrameHandle] returns [boolean]] 
RETURNS [GlobalFrameHandle]; 

Calls proc once for each global frame currently defined. If proc returns true, 
EnumerateGlobalFrames returns tlie GlobalFrameHandle of the last frame 
processed. If all global frames have been processed, NullGlobalFrame is returned. 

Warning: If new modules are created while EnumerateGlobalFrames is in control, it is 
not guaranteed that they will be included in the sequence of GlobalFrameHandles 
passed to proc. 
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Frames 

A Frame is the implementation of the procedure language constaict. All manipulation of 
Frames is done using FrameHandles. 

FrameHandle: type = pointer to Frame; 

Frame: type = record [. . .]; 

Frames may be validated by calling: 

ValidateFrame: procedure [FrameHandle]; 

Checks to see that the parameter is a valid frame; InvalidFrame is raised if not. 
InvalidFrame: signal [frame: FrameHandle]; 

Indicates that frame does not point to a valid frame. 

Module Creation / Deletion 

The following procedures allow the programmer explicit control over the creation and deletion of 
modules. NewConfig and RunConfig provide an interface for loading configurations. The 
language constaict new should be used for making copies of modules. UnNew and 
UnNewConfIg allow the deletion of previously loaded modules and configurations. 
SelfDestruct allows a module to UnNew itself and return to its caller. These operations are 
defined in FrameDefs. 

NewConfig: procedure [name: string]; 

Loads the BCD contained in the file name. A configuration loaded in this way can be 
started only by start traps or binding to and starting a frame or program which it exports. 

RunConfig: procedure [name: string]; 

Like NewConfig, except that the control module of the configuration will be started if 
there is one. 

Warning: a stack error will result if the control modules requires parameters. 

UnNewConfIg: procedure [frame: GlobalFrameHandle]; 

Deletes all global frames that are a part of the configuration containing frame, as well as 
all copies of those frames. Frees the storage for the global frames (to the segmentation 
machinery if it was obtained from there, or to the frame heap), and frees all the code 
segments. 

UnNew: procedure [frame: GlobalFrameHandle]; 

Deletes the global frame pointed to by frame. Returns the global frame to the frame heap 
(if the frame was allocated from that heap). Deletes the code segment of the frame if no 
other global frames share it. 
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Warning: there is no check for references that are bound to the module being deleted. 

The language construct new and the operation UnNew should be used for creating and destroying 
copies of modules. They are relatively inexpensive operations, and provide faciliues for using 
module instances as objects. NewConfig and UnNewConfig on the other hand, are relatively 
expensive operations, and should be used to add or remove configurations which are relatively 
static. 

SelfDestruct: procedure; 

UnNews the module of the caller, and returns to its caller's caller. 

NoGlobalFrameSlots: signal; 

Indicates that there is no room in the Global Frame Table when either NewConfig or 
RunConfig have been called or the lanuguage construct new has been invoked. 

Fine point: global frames for single modules (and copies) are allocated from the frame heap. Other configurations 
allocate their global frames as a single (data) segment, and are subject to some wasted space due to breakage. 

Other signals may be raised when Newing modules; these signals indicate that the BCD being 
loaded is invalid, versions of interfaces don't match, or code files cannot be found or compiled in 
non-Alto mode. In addition, when a module is started, the signal Start Fault may be raised (see 
the section on Traps for more information). 

Code Manipulation 

The following procedures enable the user to. control code swapping. 

MakeCodeResident: procedure [f: GlobalFrameHandle]; 

Swaps in the code for f as low as possible in memory by pushing unlocked read-only 
segments out of the way. It will first swap out the code if it is swapped in. 

LockCode: procedure [link: unspecified]; 

Swaps in and locks the code segment associated with link (which may be either a 
procedure, pointer to frame or program). The procedure GlobalFrame is used to 
find the global frame of link (and may raise the signals InvalldGlobalFrame and 
UnboundProcedure). 

Warning: calling LockCode on a global frame that has not been started will disable start 
traps on that module. 

UnlockCode: procedure [link: unspecified]; 

Unlocks the code segment associated with link (which may be either a procedure, 
pointer to frame or program). The procedure GlobalFrame is used to find the 
global frame of link (and may raise the signals InvalidGlobalFrame and 
UnboundProcedure). 
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SwapOutCode: procedure [f: GlobalFrameHandle]; 

Swaps out the code for f. 

Fine point: when a frame has its code swapped out. all the global frames that have the same code segment will 
be updated to reflect the fact that the code is swapped out. These other frames either have their code 
segments packed with that frame or they are copies of that frame. Code may be swapped out by clients 
calling SwapOutCode or by the system. 

SwaplnCode: procedure [f: GlobalFrameHandle]; 

Swaps in and locks the code for f. 

Warning: calUng SwaplnCode on a global frame that has not been started will disable 
start traps on that module. 

Miscellaneous Operations 

The following procedures are useful for debugging and determining what has been loaded. 

GetCaller: procedure returns [program]; 

Returns the module containing its caller's caller. 

IsBound: procedure [link: unspecified] returns [boolean]; 

In cases where configurations are conditionally loaded, Is Bound can be used to determine 
the presence of a module or procedure. The unspecified argument should be an imported 
procedure or program, or pointer to an imported variable. 
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This section has been taken from the Pilot Functional Specification and shghtly modified to reflect 
the Alto/Mesa implementation. 

Warning: The Alto/Mesa operating system software has not been revised and redesigned to fully 
exploit the capabilities of the new process mechanism. In particular, arbitrary preemptive processes 
are not supported, and the restrictions of Mesa 3.0 on processes running at interrupt level still 
apply. 

Most aspects of processes and monitors are made available via constructs built into the Mesa 
language and described in Chapter 10 of the Mesa Language Manual. Some facilities whose 
frequency of use does not justify such treatment are cast as procedures, and form part of tlie Mesa 
system. The types described below are defined in PSBDefs. 

PSB: PRIVATETYPE = MACHINE DEPENDENT RECORD [.,. ]; 

ProcessHandleiTYPE = pointerto PSB; 

A PSB defines the data structure underlying the Mesa process implementation. In general 
no chent programs should be concerned with these types (except possibly for debugging). 

The types and procedures described below are defined in P recess Defs. Any of the operations 
w^hich take a process as an argument (i. e., join, Abort, and Detach) may generate the 
following signal. 
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InvalidProcess: signal [process: ProcessHandle]; 

This signal indicates that the process argument does not correspond to any process known 
to the Mesa system. The check on the validity of the argument is nor infallible. In particular. Mesa is 

unable to distinguish between a process which has been deleted and a new, recently created one which 
coincidentally has the same value. 

A call to FORK may generate the following signal. 

TooManyProcesses: error; 

The Mesa system contains a fixed number of PSBs, This signal will result when there are 
no PSBs available to create a new process. 

GetCurrent: procedure returns [ProcessHandle]; 

It returns the ProcessHandle of the current process. 
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Initialization 

Every instance of a monitor and every condition variable must be initialized before it can be used. 
There are two cases: 

If the lock and the condition variables reside in the global frame (or possibly the local 
frame, in the case of the condition variables) Mesa will automatically initialize them along 
with the other global/local variables when the module is STARTed or the procedure is 
entered. 

If the lock and/or condition variables reside in client-allocated records, initialization is. the 
responsibility of the client. 

Using uninitialized monitor locks or condition variables or reinitializing monitor locks or condition \'ariables 
after they have have begun to be used will lead to totally unpredictable behavior. 

The following operations are provided for initializing monitor locks and condition variables in 
client-created data structures. 

InitializeMonitor: procedure [monitor: pointer to monitorlock]; 

InitializeMonitor leaves the monitor unlocked and sets the queue of waiting processes to 
empty. It may be called before or after the monitor data is initialized, but must be called 
before any entry procedure is invoked. Once use of the monitor has begun, 
InitializeMonitor must never be called again. 

InitializeCondition: procedure [condition: pointer to condition, ticks: Ticks]; 

InitializeCondition sets the queue of waiting processes to empty and sets the timeout 
interval of the condition variable to ticks (measured in units of "ticks" of an internal 
clock). It may be called before or after the other monitor data is initialized, but must be 
called before any wait or notify operations are performed on the condition variable. Once 
use of the condition variable has begun, InitializeCondition must never be called again. 

Clients may convert clock ticks, milliseconds and seconds using the following operations: 

Ticks: TYPE = cardinal; 

Milliseconds: type = cardinal; 

Seconds: TYPE = cardinal; 

MsecToTicks: procedure [Milliseconds] returns [Ticks]; 

TicksToMsec: procedure [Ticks] returns [Milliseconds]; 

SecondsToTicks: procedure [Ticks] returns [Seconds]; 
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Timeouts 



Condition variables which are initiahzed automatically are assigned a default timeout of a few- 
seconds. The timeout of any condition variable may be changed by die following operation. 

SetTimeout: procedure [condition: pointerto condition, ticks: Ticks]; 

DisableTimeout: procedure [pointer to condition]; 

SetTimeout adjusts the timeout interval for all subsequent wait operations applied to that 
condition variable. DisableTimeout disables timeouts for all subsequent wait operations 
applied to that condition variable. However, neither operation has any effect on processes 
which are already WAiTing. 

SetTimeout and DisableTimeout are the only available operations to adjust a condition 
variable once it has been used. In particular, InitlalizeCondition must not be used for 
tills purpose, especially for condition variables which are automatically initialized. 

Detaching Processes 

A process which will never be joined is detached using the following operation. 
Detach: procedure [process]; 

This operation sets the state of the process so that when it returns from its root procedure, 
it will be deleted immediately and its results, if any, will be discarded. If the process is 
invalid (e. g., if the process has already been deleted), tiie signal InvalidProcess may be 
generated. 

The argument lo Detach is actually of type UNSPECIFIED, and is validated as a PROCESS at ain-time. 
This is necessan- since there is no generic type which includes all PROCESS types, regardless of result types. 

Priorities of Processes 

When a process is created with fork, it inherits the priority of the FORKing process. If this proves 
unsatisfactory, the FORKed process may change its own priority with the following operation. 

SetPriority: procedure [Priority]; 

Priority: TYPE = [0..7]; 

A process may determine its own priority by calling: 

GetPriority: procedure returns [Priority]; 

There is no way for a process to alter the priority of another process. 

CAUTION: Use of multiple priorities in the Alto/Mesa implementation is severely restricted. Any 
process running at other than the default priority (currently, 1) is forbidden to use many of the 
standard runtime support features of the Mesa environment. In practice, this means that non- 
standard priorities should be used only for interiojpt handling, while all "normal" processing takes 
place concurrently at the default priority level. In addition, all interrupt level code must be locked 
in memory and' should perform only a minimal amount of processing. 
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Aborting a process 

A process can be aborted by calling the following operation. 
Abort: procedure [process]; 

The effect of this operation is to generate the signal Aborted the next time the process 
executes a wait statement on any condition variable. If the process is already WAiTing, an 
implicit NOTIFY is issued at the time this procedure is called. 

The argument to Abort is actually of type UNSPECIFIED, and is validated as a PROCESS at run-time.. This 
is necessao* since there is no generic type which includes all PROCESS types, regardless of result types. 

Aborted: error; 

The catch phrase for this signal may be attached to the wait statement, or it may be 
enabled in some scope according to the scope rules of Mesa. The catch phrase is executed 
with the corresponding monitor locked. 

The intended use of Abort is to provide a means whereby one process may hint to another that the latter 
should go away, after first cleaning up. An Abort signal may occur on any condition variable, and thus every' 
monitor should be protected by some catch phrase for it. 

DisableAborts: procedure [pointer to condition]; 

This procedure prevents a process from aborting when it waits on the specified condition 
variable. It is not implemented in Alto/Mesa. 



Control of scheduling 

The Mesa process mechanism does not attempt to allocate processor time fairly among processes of 
equal priority. Because of this, it may be desirable for a process which does not does not execute 
WAIT statements very frequently in the normal course of its computation to occasionally yield 
control of the processor by calling the following operation. 

Yield: procedure; 

This is a hint to the scheduler to run other processes of the same priority. However, there 
is no guarantee that any other process will execute before the calling process resumes 
execution, even if there are processes able to execute. 

In no case must the logical correctness of client programs depend on the presence or absence of calls to Yield: 
priorities and yielding are not intended as a process-synchronization mechanism. They are only hints to assist 
clients in meeting performance requirements. 
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Interrupt Level Processes 

This section refers only to the Alto/Mesa implementation. It should be of interest only to 
programmers of interrupt level code, 

Tlie Mesa monitor mechanism includes an extension to cover the case of communication between 
software processes and Input/Output controllers (hardware and/or firmware). This is done using 
the artifact of naked condition variables', that is, condition variables which are not effectively 
protected by a monitor lock. The need for this arises from the fact that communication with I/O 
controllers, while similar to normal interprocess communication, suffers from the problem that the 
controllers are intrinsically unable to enter monitors. This means that two important atomicity 
properties provided by monitor locks are lost: 

Atomicity of wakeups: Monitor locks eliminate the need for a traditional "wakeup waiting" 
(or 'interrupt pending") flag. Lack of the monitor lock requires the provision of such a 
flag if lost interrupts are not to result. 

Atomicity of data manipulations: The monitor lock avoids the problems of critical races on 
shared data; traditionally, I/O architectures take an ad hoc approach to this problem, rather 
than providing any general mechanism. 

The approach taken is to solve the first problem in a general way, and leave the second problem for 
case-by-case resolution by the designers of specific controller/software interfaces. (This closely 
mirrors the approach normally taken in more traditional I/O-interrupt architectures.) 

A software process that deals with an I/O controller does so from within what appears to be a 
normal monitor. The monitor data includes the status and control blocks of the device and a 
condition variable which the device notifies to raise an "interrupt". Since the controller can access 
the shared data at any time, however, special care must be taken by the software to avoid conflicts. 
Similarly, if the controller tried to notify the software between the time it decided to wait on the 
condition variable, and the time that it actually performed the wait operation, the notify would be 
lost. To prevent this, the controller does a special form of notify (a naked notify), which sets a 
wakeup-waiting flag in the condition variable. This difference is invisible to the software, which 
does a normal wait operation on the condition variable. 

The traditional operations Enablelnterrupts and Disablelnterrupts are provided for those rare 
circumstances in which seizing the entire machine is the only fonn of mutual exclusion which 
proves sufficient. Doing a wait while interrupts are disabled is not recommended.' 

InterruptLeveliTYPE = [0..15]; 

InterruptLevels correspond to the interrupt channels described in the Alto Hardware 
Manual (except that the numbering is different). Interrupt level corresponds to Alto 
interrupt channel 15, the memory parity interrupt channel. Several levels are used by the 
Mesa system. Programmers of interrupt level code should see the definitions in 
ProcessDefs. 

ConditionVector:TYPE = array InterruptLevel OF pointer to condition; 

CV: POINTER TO ConditionVector = -- magic constant •-; 

CV points to an array of pointers to the naked condition variables described above. To 
associate a condition with an interrupt level, assign a pointer to the condition to the 
corresponding element of CV (CV[level] ^ @cVar). To disable the naked notifys, 
assign nil. 
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Disablelnterrupts, Enablelnterrupts: procedure; 



These are machine code procedures which disable and enable the handling of intermpts at 
the lowest level. They should be used only in matching pairs and only when no other 
exclusion mechanism will suffice. a counter is maintained of the number of unmatched 
Disablelnterrupts so thai nested pairs will work correctly. 
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The Mesa virtual memory (VM) is organized as a vector of pages of size PageSize words; the last 
page is MaxVMPage. VM is occupied by segments: a segment is an integral number of pages in 
length and the words in a segment are all linearly addressable; segments have no empty holes in 
them. There are two variants of segments: data and file. Data segments are associated directly with 
memory and are not swappable or movable; file segments correspond to contiguous groups of pages 
in a file and may be swapped in and out of virtual memory. 

Client programs access segments using SegmentHandles, which are pointers to 
SegmentObjects. A SegmentObject contains the information necessary to describe the 
segment. Although there are some routines that deal with SegmentHandles, segments are not 
particulatily interesting unless they are discriminated as to data or file xariant. 

Client programs access file segments using FileSegmentHandles, which are pointers to file 
SegmentObjects. A file segment contains sufficient information to compute its address if the 
segment is swapped in. Internally, the segmentation package maintains a set of objects called 
FileObjects: a file object, among other things, contains the file's disk address and serial number, 
as well as its access rights. The association between a segment and a file is made when the segment 
is created. The Mesa file package is documented separately. 

Segments may also be pages in VM rather than attached to a file. Such data segments are not 
swappable or movable in any way (relative to the Mesa virtual memory). Thus, absolute pointers 
into a data segment are valid for the lifetime of the segment. DataSegmentHandles and data 
SegmentObjects are used to record information about these segments. See SegmentDefs for 
further details. 



Segments 

As mentioned above, segment objects come in two varieties: data segments and file segments The 
following structure contains the necessary information: 

SegmentHandle: type = pointer to SegmentObject; 

SegmentType: type = {data, file}; 

SegmentObject: type = record [ 
... J 

SELECT type: SegmentType from 
data => [ 

VMpage: [0.. MaxVMPage], - VM page number 

pages: [1..MaxVMPage + 1] - number of pages 

. ■ .]. 
file => [ 

swappedin: boolean, -- true iff segment is in 

read, write: boolean, - access options 
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class: FileSegmentClass, - {code, other} 

VMpage: [O..MaxVMPage], - // swapped ifu VM page number 

file: FileHandle, - see the file package 

inuse: boolean, - software LRU bit 

base: PageNumber, - first page of the file to include 

pages: [L.MaxVMPage + 1], - number of pages, beginning with base 

lock: [O.-MaxLocks], - locking reference count 

. . .], 

endcase]; 

The procedures which manipulate undiscriminated segments are: 

VMtoSegment: procedure [a: pointer] returns [SegmentHandle]; 

The handle for the segment containing the specified address (as currently laid out in 
memor>0 is returned; nil is returned if no segment contains it. This does not imply that 
the page containing the address is free, however; it may be reserved for some operation 
currently in progress. 

SegmentAddress: procedure [seg: SegmentHandle] returns [pointer]; 

The address of the beginning of the segment is returned; nil is returned if the segment is a 
file segment and not currently swapped in. To guarantee the validity of the address the 
segment should be locked when this procedure is called (see belowO, since the system may 
swap out file segments which are not locked. Beware of dangling references! 



Data Segments 

Data segments are associated only with virtual memory (there is no swapping file), and are never 
moved or swapped out. 

DataSegmentHandle: type = pointer to DataSegmentObject; 

DataSegmentObject: type = data SegmentObject; 

The procedures which manipulate data segments are: 

NewDataSegment: procedure [base: PageNumber, pages: PageCount] 
returns [DataSegmentHandle]; 

Creates a new data segment and returns a handle for it. If base is DefaultBase then the 
segment is allowed to begin on any free page in memory. If base is an actual page 
number (in [0.,MaxVMPage]), an attempt is made to place the segment at that location. 
Note that pages should not be defaulted. 

DataSegmentAddress: procedure [seg: DataSegmentHandle] returns [pointer]; 

Returns a pointer to the base of the segment in virtual memory. In the current 
implementation, segments always begin on a page boundary; this may not be true in the 
(distant) future. 
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VMtoDataSegment: procedure [a: pointer] returns [DataSegmentHandle]; 

The handle for the segment containing the specified address (as currently laid out in 
memor\') is returned, nil is returned if no data segment contains it. This does not imply 
that the page containing the address is free. howe\'er; it may be assigned to a file segment. 
or reserved for some operation cun-ently in progress. 

DeleteDataSegment: procedure [seg: DataSegmentHandle]; 

The specified data segment is deleted and its segment object freed. When a segment is 
successfully deleted, any VM which it occupied becomes free. 

EnumerateDataSegments: procedure [ 

proc: procedure [DataSegmentHandle] returns [boolean]] 
returns [DataSegmentHandle]; 

Calls proc once for each data segment currently defined. If proc returns true, 
EnumerateDataSegments returns the handle of the last segment processed. If the end 
of the set of data segments is reached, nil is returned. 

If data segments are created while EnumerateDataSegments is in control, it is not guaranteed 
that they will be included in the sequence of DataSegmentHandles passed to proc. 



File Segments 

Unlike data segments, file segments are associated with a contiguous group of pages in a file and 
are therefore swappable. Pointers into a file segment are valid only while it is swapped in (and 
locked so that it will not be swapped out). A file segment which is swapped out occupies no space 
in virtual memory, other than the segment object w^hich describes it. If the LRU bit (inuse) is set, 
the swapper will ignore this segment on its first search for free pages. The swapper resets this biL 
so the segment will be considered if a second pass is necessary. 

FileSegmentHandle: type = pointer to FileSegmentObject; 

FileSegmentObject: TYPE = file SegmentObject; 

To create new file segments, use 

NewFileSegment: procedure [ 

file: FileHandle, base: PageNumber, pages: PageCount, access: AccessOptions] 
returns [FileSegmentHandle]; 

Creates a new segment and returns a handle for it. The segment is associated with the 
corresponding file pages, but the file is not opened and the segment is not swapped in. If 
base is DefaultBase, the segment will begin with the first data page of the file, and if 
pages is DefaultPages, it will include the last page of the file. Although it is generally 
not done, a segment can begin with the leader page (page zero) of a file. Finally, if 
access is DefaultAccess, read access is assumed. 

If the access specifies that changing the data is permitted, then whenever it is necessary to swap this 
segment out and remove its pages from memory, pages will be written to the file (the Alto has no 
hardware to detect if the pages have actually been changed). Note that it is possible to change the 
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segment^s access (by setting the write bit. for example), provided the file to which it is attached has 
the appropriate access rights. 

FileSegmentAddress: procedure [seg: FileSegmentHandle] returns [pointer]; 

The address of the beginning of the segment is returned. The signal SwapError is raised 
if the segment is not currently swapped in. To guarantee the validity of the address, the 
segment should be locked when this procedure is called (see below), since the system may 
swap out file segments which are not locked. Beware of dangling references! 

VMtoFileSegment: procedure [a: pointer] returns [FileSegmentHandle]; 

The handle of the file segment containing the specified address (as currently laid out in 
memory) is returned; nil is returned if no file segment contains it. This does not imply 
that the page containing the address is free, however; it may be assigned to a data segment, 
or reserved for a segment currently being swapped in. 

DeleteFileSegment: procedure [seg: FileSegmentHandle]; 

The specified file segment is deleted and its segment object is released. If the segment is 
swapped in, it is first sw^apped out (it should not be locked). If there are no other segments 
associated with this segment's file (the file's segcount is zero), then ReleaseFile is called 
to release the FileObject. When a segment is successfully deleted, any VM which it may 
have occupied becomes free. 

EnumerateFlleSegments: procedure [ 

proc: procedure [FileSegmentHandle] returns [boolean]] 
returns [FileSegmentHandle]; 

Calls proc once for each data segment currently defined. If proc returns true, 
EnumerateFlleSegments returns the handle of the last segment processed. If the end 
of the set of data segments is reached, nil is returned. 

If file segments are created while EnumerateFlleSegments is in control, it is not guaranteed 
that they will be included in the sequence of FileSegmentHandles passed to proc. 

Window Segments 

A window segment is similar to a file segment, except that the base and pages fields of the 
segment may be altered (using the procedures described below) after it is created, in order to slide 
the window around in a file or to vary the window's size. In reality, all file segments are in fact 
window segments, and may be moved with the following procedure: 

MoveFileSegment: procedure [ 

seg: FileSegmentHandle, base: PageNumber, pages: PageCount]; 

If the segment is swapped in, it is first swapped out (it should not be locked). The segment 
is then moved to the new location in the segment's file, but it is not swapped in. The 
base and pages are defaulted as in NewFileSegment. 

Fine point: in the current implementation, the disk address of the original segment is retained as a hint about 
the new location, thus improving performance considerably when a one page segment is slid foruard or 
backward in a file. 



Alto/Mesa Segment Package 51 

If the original and final position of the segment overlap, there is no guarantee that the overlapping 
pages are actually written, nor is it guaranteed that a minimum number of pages are transferred. 
The segment package reserves the option to implement (or not to implement) such optimizations in 
the future. 



Swapping Segments 

A segment can be swapped into and out of VM. The procedures and signals w^hich implement this 
are described in this section: 

Swapin: procedure [seg: FileSegmentHandle]; 

Swaps in the specified segment (if it is swapped out), opening the associated file if 
necessary; locks it so it won't be moved or swapped out. A SwapError will result if the 
segment already has MaxLocks locks on it, or if the segment's file has MaxRefs segments 
currently attached to it and swapped in. 

To unlock a segment (allow it to be swapped), use the procedure 

Unlock: procedure [seg: FileSegmentHandle]; 

Unlocks the specifed segment so that it can be swapped out. Note that locking behaves like 
reference counting, so that locks (performed by Swapin) must be properly paired with 
Unlocks. 

A segment is swapped out using 

SwapOut: procedure [seg: FileSegmentHandle]; 

Swaps out the specified segment, writing the pages back to the file if the segment's access 
makes this necessary, and free the segment's VM pages. If the segment is locked, a 
SwapError will be generated. 

A program may explicitly request that the file pages corresponding to a segment be updated by 
calling: 

SwapUp: PROCEDURE [seg: FileSegmentHandle]; 

Write the pages of the segment back to the file if the access requires it. This operation 
does not unlock the segment or free the segment's VM pages. 

Note that neither Swapin, SwapOut, or SwapUp are capable of extending a file (physically 
adding pages or bytes to it) based on the size of a segment. Segments may be attached only to 
pages of a file that are already allocated on the disk (and chained together). Extending (or 
contracting) a file must be done using other mechanisms (for example, see SetEndOfFile in the 
file package). 
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Signals 

The following signals may be generated by the segment package: 

tnvalidSegmentSize: signal [pages: PageCount]; 

In NewDataSegment or NewFileSegment a zero length segment has been requested. 
or the length exceeds the size of virtual memory. 

InsufficienlVM: signal [needed: PageCount]; 

In NewDataSegment or Swapin there is not enough contiguous memory to accomodate 
a segment; needed is the number of pages that are actually required. If resumed, the 
allocation will be retryed; this gives the catcher of this signal a chance to free up some VM. 
Users can free VM pages by deleting data segments and by allowing locked segments to 
become swappable (see also the section below on swapping strategies). 

VMnotFree: SIGNAL [base: PageNumber, pages: PageCount]; 

In NewDataSegment the base was not Def aultBase and the specified memory pages w^ere 
not free. 

SwapError: signal [seg: FileSegmentHandle]; 

An invalid sw^apping operation was attempted with seg. 

SegmentFault: signal [seg: FileSegmentHandle, pages: PageCount]; 

End of file was encountered while attempting to swap the segment in or out; pages is the 
actual number of pages in the segment. If pages is greater than zero then the signal may 
be resumed; the segment will be tamcated accordingly (of course, this will not alter the file 
length). 

Low Level Memory Allocation 

Operations are provided for users that have a need to control memory allocation at a lower level 
than provided above. Allocation is controlled by the information in an A Hoc Info (which is passed 
along with each operation). 

Alloclnfo: type = record [ 

effort: {hard, easy}, 

direction: {topdown, bottomup}, 

. . . ]; 

If the effort field is hard, unlocked read-only file segments will be pushed out of the way. The 
direction field specifies the direction of the search for a hole. In the above procedures, data 
segments are allocated topdown, and file segments are allocated bottomup. See AllocDefs for 
further information. 

The operations which form the low-level memory allocation are: 
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MakeDataSegment: procedure [ 

base: PageNumber, pages: PageCount, info: Alloclnfo] 
RETURNS [DataSegmentHandle]; 

Acts like NewDataSegment, except info is passed as an additional parameter; the same 
restrictions apply and tlie same signals may be generated. 

MakeSwappedIn: procedure [ 

seg: FileSegmentHandle, base: PageNumber, info: Alloclnfo]; 

Acts like Swapin, except info and base are passed as additional parameters; the same 
restrictions apply and the same signals may be generated. If base is Default Base then 
the segment is allowed to begin on any free page in memory. If base is an actual page 
number (in [O..MaxVMPage]), an attempt is made to place the segment at that location 
(VMnotFree will be raised if the specified pages are not available). 



Swapping Strategies 

A mechanism is provided for infonning the segmentation package of emergency measures which can 
be taken when the signal InsufficientVM is (about to be) generated. These measures take the 
form of SwappingProcedures which, when called by the swapping manager, attempt to make 
more room in virtual memory and return a boolean indicating their success or failure to do so. 
The swapping manager invokes each procedure in turn, retrying the allocation after each procedure 
which has indicated success, until sufficient memory is obtained. If all such procedures indicate 
failure, the signal InsufficientVM is raised (the swapping manager is not crying wolf!). 

The swapping strategies are maintained as a linked list of SwapStrategy nodes whose procedures 
are invoked from head to tail. 

SwappingProcedure: type = procedure [ 

needed: PageCount, info: Alloclnfo, seg: SegmentHandle] 

RETURNS [boolean]; 

The following parameters are supplied to swapping procedures to allow them the make intelligent 
decisions about making room: needed is the number of pages requested, info the Alloclnfo 
supplied to the allocator, and seg the file segment that will use the allocated memory (nil if the 
segment is not known). 

SwapStrategy: type = record [ 
link: pointer to SwapStrategy, 
proc: SwappingProcedure]; 

The swapping manager initializes the list with a single node which invokes code swapping as a last 
resort. 

StrategyList: pointer to SwapStrategy ♦- ©LastResort; 

LastResort: SwapStrategy = SwapStrategy[NiL, TryCodeSwapping]. 

Swapping procedures are added to and removed from the list by the procedures: 
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AddSwapStrategy: procedure [strategy: pointer to SwapStrategy]; 

The specified strategy node strategy is added to the head of the Ust of swapping 
procedures. If strategy is already on the list, its position and content are not disturbed, 

RemoveSwapStrategy: procedure [strategy: pointer to SwapStrategy]; 

The specified strategy node s is removed from the list of swapping procedures. 

Currently, TryCodeSwapping uses an (approximately) LRU (least-recently-used) algorithm to 
choose a code segment to swap out. Only code segments which are not locked are considered. 
Unlocked read-only file segments are also swapped out by TryCodeSwapping. 

Since it is unattractive to require that swapping strategies (other than TryCodeSwapping) be 
locked, swapping procedures should observe the following conventions. If such a procedure obtains 
a state in which it has nothing to swap, it should either remove the node containing it from the 
strategy list or change the procedure in the node to be 

CantSwap: SwappingProcedure; 

Because CantSwap is part of the swapping manager (and therefore locked), this will avoid 
swapping in a strategy procedure which knows it has nothing to do. 



Miscellaneous Procedures 

The following procedures implement conversion between memory addresses and virtual memory 
page numbers. 

PageFromAddress: procedure [a: pointer] returns [PageNumber]; 

AddressFromPage: procedure [p: PageNumber] returns [pointer]; 

PagePointer: procedure [a: pointer] returns [pointer]; 

PagePointer returns the address of the beginning of the page which contains its 
argument. 

The following procedures implement conversion between FileSegments and DataSegments. 
Note that both segments must exist at the time of the call, and neither is destroyed. They must be 
of die same length (a SwapError will result otherwise), 

CopyDataToFileSegment: procedure [ 

dataseg: DataSegmentHandle, fileseg: FileSegmentHandle]; 

initializes a file segment to be the contents of a data segment. 

CopyFileToDataSegment: procedure [ 

fileseg: FileSegmentHandle, dataseg: DataSegmentHandle]; 

initializes a data segment to be the contents of a file segment. 



:>5 



Alto/Mesa Storage Management Facilities 

April 1979 



Two collections of Mesa procedures are available for acquiring and managing storage areas. The 
segtnentation machinery^ which is described in detail elsewhere, pro\-ides contiguous groups o^ pages 
(256 word blocks) in the virtual memory. A simplified interface with that machinery is described 
below. There is also a Mesa free storage package for managing arbitrarily sized nodes within free 
storage zones. Since all state information is recorded within the zones themselves, the system- 
provided instantiation of the latter package can manage an arbitrary number of zones. There is one 
system-defined zone, called the free storage heap, available for general use; special procedures exist 
for creating and destroying nodes within it. The salient characteristics of these packages are 
summarized below. 

The segmentation machinery is most suitable for obtaining large blocks of storage. All bookkeeping 
information associated with such blocks is recorded in auxiliary tables that are managed by the 
segmentation system, not in the blocks themselves. Allocating or releasing a segment involves 
searching and updating a number of those tables. On the other hand, any freed page becomes 
available for general use by the system (loading, buffering, etc.) and any two adjacent free pages can 
be coalesced to become part of a new segment. 

The free storage package is a transliteration of a BCPL program by Ed McCreight that was itself 
based upon a suggestion by Don Knuth {The Art of Computer Programming, Volume 1, p. 453, 
#19). Within a zone, free nodes are kept as a linked list. One hidden word containing 
bookkeeping information is stored with each allocated node, and additional bookkeeping 
information is kept in the header of each zone. Allocation and release of nodes are usually very 
fast. Adjacent free nodes are always able to be coalesced. It is also possible to add new areas of 
storage to enlarge a zone. These new areas are linked together so that they may be deleted if all 
the nodes in an area are free; in addition, an entire zone may be deleted. 

The free storage package performs best when the sizes of nodes are small compared to die sizes of 
the block(s) making up the zone. In. particular, the system's heap is intended to be used for small, 
transient data structures, such as the nodes of a temporary list structure or the bodies of (short) 
strings when the maximum length must be computed dynamically or the structure must outlive the 
frame that creates it. Use of the heap for large (i.e., multipage) nodes decreases flexibility in 
storage management, since the additional pages may become a permanent part of the zone. 

The allocators in both packages return absolute pointers; allocated nodes are not relocatable and 
there is no garbage collection or automatic deallocation of any sort. Also, the values returned by 
the allocators are free pointers (type pointer to unspecified) which must be cast appropriately 
(usually by assignment) before they can be used. 
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Segmentation Interface 

The following definitions are contained in SystemDefs. 

AllocateSegment: procedure [nwords: cardinal] returns [base: pointer]; 

Allocates a segment of virtual memory containing at least nwords words and returns the 
address of the first word in that segment. AllocateSegment provides a simple interface 
to NewDataSegment for allocating VM segments only; see the description of that 
procedure for further explanation. 

AllocateResidentSegment: procedure [nwords: cardinal] returns [base: pointer]; 

Behaves like AllocateSegment, except that unlocked read-only file segments are pushed 
out of the way when the segment is allocated. 

SegmentSize: procedure [base: pointer] returns [nwords: cardinal]; 

Returns the number of words actually obtained in the segment. 

These procedures allow complete utilization of segments obtained without knowledge of page 
structure and guaranteed only to have some minimum size. Such segments are returned to the 
system by 

FreeSegment: procedure [base: pointer]; 

For uses in which the page staicture is already known, the following procedures are also provided. 
AllocatePages: procedure [npages: cardinal] returns [base: pointer]; 
AllocateResidentPages: procedure [npages: cardinal] returns [base: pointer]; 
PagesForWords: procedure [nwords: cardinal] returns [npages: cardinal]; 
FreePages: procedure [base: pointer]; 

Any storage obtained using AllocatePages or AllocateResidentPages is guaranteed to begin 
on a page boundary. 

Free Storage Package 

The following definitions are available in FSPDefs. A zone is a block of storage containing 
embedded nodes. The length of either a zone or a node is 

BlockSize: type = integer [O..VMLimit/2]; - 15 bits. 

Each zone is headed by a ZoneHeader, which is a monitored record with the following public 
fields: 

threshold: BlockSize, -- minimum node size in zone 
checking: boolean, - zone checking (see below) 
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Zones are identified by pointers of type 
ZonePointer: type = pointer to ZoneHeader; 

Associated with each zone is a procedure of type 
Deallocator: type = procedure [pointer]; 

which is used to deallocate the storage used by the zone. The following Deallocator may be 
supplied when nothing is to be done to the storage being freed: 

DoNothingDeatlocate: Deallocator; 

Zone Operations 

An arbitrary block of (uninterpreted) storage is converted to a zone by the procedure 

MakeNewZone: procedure [ 

base: pointer, length: BlockSize, deallocate: Deallocator] 
RETURNS [z: ZonePointer]; 

Such a block can alternatively be made an extension of an existing zone by calling 

AddToNewZone: procedure [ 

z: ZonePointer, base: pointer, length: BlockSize, deallocate: Deallocator]; 

The following procedures default DoNothingDeallocate as the Deallocator: 
MakeZone: procedure [base: pointer, length: BlockSize] returns [z: ZonePointer]; 
AddToZone: procedure [z: ZonePointer, base: pointer, length: BlockSize]; 

Unused areas of the zone are released by calling 

PruneZone: procedure [z: ZonePointer] returns [boolean]; 

which returns true if any areas were freed and false otherwise. 

A zone may be destroyed and all its storage freed by calling 

DestroyZone: procedure [z: ZonePointer]; 

No check is made for any nodes that are in use. 

Warning: This operation cannot be protected by the monitor, and can therefore result in 
severe errors if another process is inside the zone. 

Node Operations 

The largest node that can be allocated in a virgin block of size length is length-ZoneOverhead. 

A node is allocated by 

MakeNode: procedure [z: ZonePointer, n: BlockSize] returns [pointer]; 
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The value returned points to a block of n words; there is an additional hidden word of 
overhead (at offset-1) which must be preserved by users of the node. Nodes are sometimes 
split to satisfy allocation requests. Splitting within a zone z never generates fragments with 
size less than z, threshold, which is initiahzed to the minimum size of a free node. A 
request for a node of size n will produce a node with size in the range [n . . 
n + z. threshold). 

The actual size of an allocated node is returned by 

NodeSize: procedure [p: pointer] returns [BlockSize]; 

If after coalescing all free nodes, a node of the requested size cannot be found, 

NoRoomlnZone: signal [z: ZonePointer]; 

is raised. This signal can be resumed (after, e.g., adding to the zone), and another attempt to 
allocate and return a suitable node will be made. An allocated node is returned to the zone by 

FreeNode: procedure [z: ZonePointer, p: pointer]; 

Alternatively, an existing node can be split by calling 

SplitNode: procedure [z: ZonePointer, p: pointer, n: BlockSize]; 

the first n words of the node p remain allocated, and the remainder of the node is freed. 

When a zone z is created, the variable z. checking is initialized to false. If that variable is set to 
true, the zone is checked for consistency prior to each transaction involving that zone. A failure 
raises one of the following signals: 

InvalidZone, InvalidNode: error [pointer]; 

Allocation From The Heap 

Clients who use heap storage extensively are encouraged to create their own heap from the above 
operations. The following procedures provide a simple interface to the free storage package. 

myHeap: FSPDefs. ZonePointer <- nil; 

GetSpace: procedure [nwords: cardinal] returns [p: pointer] = 
begin open SystemDefs, FSPDefs; 
np: cardinal; 

p ^ MakeNode[myHeap, nwords ! 
NoRoomlnZone => 
begin 

np *- PagesForWords[nwords + ZoneOverhead + NodeOverhead]; 
AddToNewZone[ 

myHeap, AllocateResidentPages[np], np*AltoDefs.PageSize, FreePages]; 
resume 
end]; 

RETURN 

end; 
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FreeSpace: procedure [p: pointer] = 

BEGIN 

FSPDefs.FreeNode[myHeap, p]; 

RETURN 
END; 

GetString: procedure [nchars: cardinal] returns [s: string] = 

BEGIN 

s ^ GetSpace[StringDefs.WordsForString[nchars]]; 
St <- [length: 0, maxlength: nchars, text:]; 

RETURN 
END; 

FreeString: procedure [s: string] = LOOPHOLE[FreeSpace]; 

InitHeap: procedure [npages: cardinal] = 
BEGIN open SystemDefs, FSPDefs; 
IF myHeap # nil then EraseHeap[]; 
myHeap <- MakeNewZone[ 

AllocateResidentPages[npages], npages *AltoDefs.PageSize, FreePages]; 

RETURN 

end; 
EraseHeap: procedure = 

BEGIN 

FSPDefs.DestroyZone[myHeap]; 

myHeap ^ nil; 

return 

end; 

Clients who use the heap infrequently may use the system storage heap. The following definitions 
are available in SystemDefs. The heap is managed by the free storage package; the appropriate 
zone pointer for use with the procedures described in the previous section is returned by 

HeapZone: procedure returns [ZonePointer]; 

The following procedures provide a specialized interface. 

AllocateHeapNode: procedure [nwords: cardinal] returns [p: pointer]; 

FreeHeapNode: procedure [p: pointer]; 

In addition, 

AllocateHeapString: procedure [nchars: cardinal] returns [s: string]; 

allocates space for the body of a string in the heap. The field s. length is set to zero; 
s. maxlength is set to nchars. 



60 Alto/Mesa Storage Management Facilities 

Such strings are freed by 

FreeHeapString: procedure [s: string]; 

If an allocation request cannot be satisfied from existing heap storage, an attempt is made to extend 
the heap with a block of appropriate size obtained from the segmentation machinery. The 
extension becomes a permanent part of the heap. 

The heap may be pruned by calling 

PruneHeap: procedure returns [boolean]; 

which returns true if any storage was returned to the segmentation machinery, and false 
otherwise. 
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StreamlO contains a set of procedures for convenient use of the character and string stream 
facilities in Mesa. The procedures of the StreamlO package are described below. The 
declarations necessary to use the procedures are in lODefs. 

StreamlO uses two streams, one for input and one for output. These may be gotten by calling: 

GetlnputStream, GetOutputStream: procedure returns [StreamHandle]; 

Returns the stream used for input or output, respectively. 
The streams may be changed by calling: 
SetlnputStream, SetOutputStream: procedure [StreamHandle]; 

Replaces the input or output stream, respectively. 

Character 10 
ReadChar: procedure returns [character]; 

Returns the next character from the , InputStream. 
WriteChar: procedure [c: character]; 

The character c is written on the OutputStream. 

Definitions for control characters such as NUL, BS, TAB, LF, FF, CR, ESC, SP, DEL, and 
ControlA - ControlZ can be found in lODefs. 

String Input 

The procedures below read input from the InputStream. The following exceptional conditions may 
occur. 

LineOverflow: signal [s: string] returns [ns: string]; 

The input has filled the string s, the current contents of the string is passed as a parameter 
to the signal. The catch phrase should return a string ns with more room. 
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Rubout: signal; 

The DEL key was typed during ReadEditedString. 

The SetEcho procedure controls the echoing of characters on input. It returns the previous state 
of the echoing mode which is defaulted to on. 

SetEcho: procedure [new: boolean] returns [old: boolean]; 

The input procedures are: 

ReadEditedString: procedure [ 

s: string, t: procedure [character] returns [boolean], newstring: boolean] 
returns [character]; 

s contains (on return) the string read from the Input St ream. The procedure t should 
return true if the character passed to it should terminate the string. If (newstring is 
TRUE and the first input character is esc) or (newstring is false), then s is treated as if 
it had been read from InputStream (input characters are appended to it). Otherwise s is 
initialized to be empty before reading is begun. 

A string is read from the InputStream with the following editing characters recognized: 

TA, tH (BS) delete the last character 

tw, to delete the last word 

tx delete the line and start over 

tr retype the line 

TV quote the next character 

If echoing is on all characters except the terminating character are echoed on the OutputStream. 
The user supplied procedure t determines which character(s) terminate the string. The character 
returned is the character which terminated the string and is not echoed or included in the string. 

The following procedures all call ReadEditedString passing true for newstring. 

ReadString: procedure [s: string, t: procedure [character] returns [boolean]]; 

Like ReadEditedString except that the terminating character is echoed. No value is 
returned. 

ReadLine: procedure [s: string]; 

Reads from the InputStream up to the next carriage return character using 
ReadEditedString. The terminating character is not part of s. 

ReadID: procedure [s: string]; 

Uses ReadEditedString to read a string terminated with a space or carriage return into s. 
The terminating character is not echoed. 
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String Output 
WriteString: procedure [s: string]; 

The string s is written on the OutputStream. 
WriteLine: procedure [s: string]; 

The string s is written on the OutputStream followed by a carriage return. 

Number Input 

These procedures use the St ringloN umber conversion procedures from the Strings package. 
ReadNumber: procedure [default: unspecified, radix: cardinal] 

RETURNS [unspecified]; 

ReadID followed by StringToNumber. The value default will be displayed if ESC is 
typed, radix is a default value, use the "B" or "D" notation to force octal or decimal. 
radix values other than 8 or 10 cause unpredictable results. 

ReadDecimal: procedure returns [integer]; 

ReadID followed by StringToDecimal. 
ReadOctal: procedure returns [unspecified]; 

ReadID followed by StringloOctal. 

Number Output 

NumberFormat: type = record [ 

base: [2. .36], zerofill, unsigned: boolean, columns: [0..255]]; 

refers to a number whose base is f.base; the field is f. columns wide; if f. zerofill, the 
extra columns are filled with zeros, otherwise spaces are used; if f .unsigned, the number 
is treated as unsigned. 

OutNumber: procedure [StreamHandle, unspecified, NumberFormat]; 

Converts the value to a character string of digits as specified by the NumberFormat and 
outputs them to the StreamHandle. 

WriteNumber: procedure [unspecified, NumberFormat]; 

Equivalent to OutNumber with OutputStream as the StreamHandle. 
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WriteDecimal: procedure [n: integer]; 

The value of n is converted to a character string of digits in base ten and output to the 
OutputStream. Negative numbers are written with a preceeding minus sign ('-)• 

WriteOctal: procedure [n: unspecified]; 

The value of n is converted to a character string of digits in base eight and output to the 
OutputStream. The numbers are unsigned, i.e.. -2 is written as 177776B. The "B" is 
appended to any number more than one digit long. 



Initialization 

The Mesa system provides an instance of StreamlO which will obtain input from the keyboard 
and write output to the display. Client programs may create new instances of StreamlO to deal 
with other streams by writing: 

StreamlO: from "streamlo"; 

imports . . . systemic: StreamlO . . - ; 

f: POINTER TO FRAME [StreamlO]; 

f *- NEW systemic; 

START f; 

The streams used for input and output can then be set by calling Set InputSt ream or 
SetOutputStream. The desired stream procedures may be accessed by OPENing f or writing 
f.prccedurename. 
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Streams provide a standard interface between programs and their sources of sequential input and 
their sinks for sequential output. A set of standard operations defined for all types of streams is 
sufficient for all ordinary input-output requirements. In addition, most streams have special (device 
dependent) operations defined for them; programs which use such operations thereby forfeit 
complete compatibility. 

Streams transmit information in atomic units called items. Usually an item is a character or a 
WORD, and this is the case for most of .the streams supplied with Mesa. Of course, a stream 
supplied to a program must have the same ideas about the kind of item it handles as the program 
does; otherwise confusion will result. Normally, streams which transmit text use character items, 
and those w^hich transmit binary information use words. 

Streams are passed about using StreamHandles, variants of which are produced by the (device 
dependent) procedures that create streams. A StreamHandle is a pointer to a variant record of 
type StreamObject, which is defined (in StreamDefs) as follow^s: 

StreamHandle: type = pointer to StreamObject; 

KeyboardHandle: type = pointer to Keyboard StreamObject; 
DisplayHandle: type = pointer to Display StreamObject; 
DiskHandle: type = pointer to Disk StreamObject; 

StreamObject: type = record [ 
reset: procedure [StreamHandle], 
get: procedure [StreamHandle] returns [unspecified], 
putback: procedure [StreamHandle, unspecified], 
put: procedure [StreamHandle, unspecified], 
endof: procedure [StreamHandle] returns [boolean], 
destroy: procedure [StreamHandle], 
link: StreamHandle, 
body: select type: * from 

Keyboard => . . . 

Display => . . . 

Disk => . . . 

Other => [type: unspecified, data: pointer]; 

The procedures which create streams return descriminated pointers (a DiskHandle, for example), 
which can be assigned to variables of type StreamHandle without any loopholes. Most stream 
procedures (and all of the standard operations) expect StreamHandles (which can be matched by 
any descriminated pointer); they check at runtime for the appropriate stream type. 

Error conditions are reported in a fashion independent of the particular stream type, using the 
following definitions (not all error codes are applicable to all stream types): 
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StreamError: signal [stream: StreamHandle, error: StreamErrorCode]; 

StreamErrorCode: type = { 

StreamType, St ream Access, St reamOpe ration, 
StreamPosition, StreamEnd, StreamBug}; 

As the definition implies, each stream object contains procedures that implement the standard 
stream operations, as described below (s is a StreamHandle, i is an item of the appropriate type, 
and "code error'* means that signal StreamError[s, code] is raised): 

reset[s] restores the stream to some initial state, generally as close as possible to the state 
it is in just after it is created. 

get[s] returns the next item; StreamAccess error if s cannot be read or if endof[s] is 
true before the call. 

putback[s, i] modifies the stream so that the next get[s] will return i and leave s in the 
state it was in before the putback. 

put[s, i] writes i into the stream as the next item; StreamAccess error if the stream 
cannot be written; StreamEnd error if there is no more space in the stream. 

endof[s] true if there are no more items to be gotten from s. For output streams, 
endof is device-dependent. 

destroy [s] destroys s in an orderly way, freeing the space it occupies. Note that this has 
nothing to do with deleting any underlying data structures or processes associated wdth the 
stream (like a disk file, for example, or the keyboard process). 

Each of these operations is defined more precisely in the descriptions of the individual stream types 
which appear separately. All of the stream routines produce the StreamType error when the 
variant of the StreamObject they are passed is not what they are expecting. See the Disk 
Streams, Display, and Keyboard sections for details of specific stream types. For each 
StreamType, there is a create procedure which returns a StreamHandle. To invoke get for a 
StreamHandle, s, simply say s.get[s]. 

The Other variant of a StreamObject is provided so that cHents can easily provide other types 
of streams using the same standard set of operations. The data field of an Other StreamObject 
should point to any additional data required by the particular stream. Clients with more than one 
type of Other stream should include a type code in the type field. 
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This module contains procedures that implement various string operations. The necessary type and 
PROCEDURE declarations appear in StringDefs and are described below. (Constants defining word 
size, character size, etc. are in AltoDefs.) Specific language features concerning strings are 
described in more detail in the Mesa Language Manual (see the index). 

SubStringDescriptor:TYPE = record [ 
base: string, 
offset, length: cardinal]; 

Substring: pointer to SubStringDescriptor; 

A SubStringDescriptor describes a region within a string. The first character is 
base[offset] and the last character is base[offset + length-1]. 

WordsForString: procedure [nchars: cardinal] returns [cardinal]; 

Calculates the number of words of storage needed to hold a string of length nchars. The 
value returned includes any system overhead for string storage. 

LowerCase: procedure [character] returns [character]; 

Changes upper case characters into lower case ones. This is a noop if the character is not a 
letter. 

Uppercase: procedure [character] returns [character]; 

Changes lower case characters into upper case ones. This is a noop if the character is not a 
letter. 



String Construction 

AppendChar: procedure [s: string, c: character]; 

Appends the character c to the end of the string s; s. length is updated; s.maxlength is 
unchanged. 

AppendString: procedure [to, from: string]; 

Appends the string from to the end of the string to; to.length is updated; 
to.maxlength is unchanged. 
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AppendSubString: procedure [to: string, from: Substring]; 

Appends the substring in from to the end of the string in to; to. length is updated: 
to.maxlength is unchanged. 

StringBoundsFault: signal [s: string] returns [ns: string]; 

An attempt was made to increase the length of s to be larger than s.maxlength. The 
catch phrase should return a string ns with more room. 

DeleteSubString: procedure [s: Substring]; 

Deletes the substring described by s from the string s.base; s. base. length is updated; 
s.base.maxlength is unchanged. 



String Comparison 

EqualString, EqualStrings: procedure [s1 , s2: string] returns [boolean]; 

Returns true if s1 and s2 contain exactly the same characters. 

EquivalentString, EquivalentStrings: procedure [si , s2; string] returns [boolean]; 

Returns true if s1 and s2 contain the same characters except for case shifts. Note: strings 
containing control characters may not be compared correctly, 

EqualSubString, EqualSubStrings: procedure [s1 -, s2: Substring] returns [boolean]; 

Analogous to EqualString and EqualStrings. 

EqulvalentSubString, EquivalentSubStrings: procedure [s1 , s2: Substring] 
returns [boolean]; 

Analogous to EquivalentString and EquivalentStrings. 

String to Binary Conversion 

StringToNumber: procedure [s: string, radix: cardinal] returns [unspecified]; 

The characters of s are interpreted as a number whose value is returned. , radix is used in 
the conversion unless the "B" or "D" notation is used to force octal or decimal. Supplying 
radix values of other than 8 or 10 is not supported. 

StringToDecimai: procedure [s: string] returns [integer]; 

Calls StringToNumber[s, 10]. 
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StringToOctal: procedure [s: string] returns [unspecified]; 

Calls StringToNumber[s, 8]. 

StringToLongNumber: procedure [s: string, radix: cardinal] returns [long integer]; 

The characters of s are interpreted as a long integer whose value is returned, radix is 
used in the conversion unless the "B" or "D" notation is used to force octal or decimal. 
Supplying radix values of other than 8 or 10 is not supported. 

InvalidNumber: signal; 

A string is not a valid number if it is empty or contains characters other than digits (a 
leading '- and trailing 'B or 'D with scale factor are allowed). 

Binary to String Conversion 

AppendNumber; procedure [s: string, n, radix: cardinal]; 

The value of n is converted lo text using radix and appended to s; radix should be in 
the interval [2.. 3 6]. 

AppendDecimal: procedure [s: string, n: integer]; 

IF n < THEN AppendChar[s, '-]; AppendNumber[s, ABS[n], 10]. 
AppendOctal: procedure [s: string, n: unspecified] ; 

AppendNumber[s, n, 8]; AppendChar[s, *B]. 
AppendLongDecimal: procedure [s: string, n: long integer]; 

Appends '- to s if n is negative. It then calls AppendLongNumber with a radix of 10. 

AppendLongNumber: procedure [s: string, n: long unspecified, radix: cardinal]; 

The value of n is converted to text using radix and appended to s; radix should be in 
the interval [2.. 3 6]. 
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TimeConvert contains procedures that implement various operations on dates and times. Tlie 
necessary type and procedure declarations appear in TimeDefs and are described below. 

PackedTimeiTYPE = long cardinal; 

A PackedTime is the number of seconds since midnight January 1, 1901 GMT. 

DefaultTime: PackedTime; 

UnpackedTimeiTYPE = record [ 

year: [0..2050], ■■ years less than 1901 are not possible 

month: [0..1 2), ■■ January = 

day: [0., 31], •- first day of month = 1 

hour: [0.. 24), 

minute: [0..60), 

second: [0..60), 

weekday: [0..6], •■ Monday = 

zone: [-1 2..1 2], ■• Pacific = 8 

dst: boolean]; 

CurrentDayTime: procedure returns [time: PackedTime]; 

Returns the current date and time in packed format. 

UnpackDT: procedure [PackedTime] returns [time: UnpackedTime]; 

Converts a packed format time to a more convenient unpacked format. If the argument is 
DefaultTime, the current time is used. 

PackDT: procedure [unp: UnpackedTime, computeDST: boolean] 
returns [time: PackedTime]; 

Converts unp into packed format. If computeDST is true, the time zone and daylight 
savings time are computed according to local conventions rather than taken from unp. If 
any of the fields of unp contain illegal values, PackDT will signal InvalidTime. 

InvalidTime: error; 

PackDT has discovered illegal values in the unpacked time. 

AppendDayTime: procedure [s: string, u: UnpackedTime]; 

Converts u to a text string of the form 12-Jan-78 14:56:13 and appends it to s. 
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AppendFullDayTime: procedure [s: string, u: UnpackedTime]; 

Like Append DayTime except that the time zone is included, e,g, l-May-78 14:56:13 
PDT. 
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All traps generated by Mesa are convened into signals or errors of the same name. Except for the 
parity error and stack error traps, all of the signals described below are related to specific language 
features and are described in more detail in the Mesa Language Manual (see the index). 

StartFauIt: signal [dest: GlobalFrameHandle]; 

An attempt was made to start or restart the frame dest, but it is not a valid global frame. 
Usually this means that a module or program was not bound, a program being restarted 
does not stop, or a module that has parameters is being started as a result of a start trap. 

ControlFault: signal [source: FrameHandle] returns [ControlLink]; 

An attempt was made to transfer to a null control link while executing in the frame 
source. Usually this means some external links have been clobbered. This signal can be 
resumed with a control link that will be used to retry the transfer. 

UnboundProcedure: signal [dest: ControlLink] returns [ControlLink]; 

An attempt was made to transfer to dest but it had an unbound tag. Usually this means 
some external links have not been bound or the gft entry of dest is null (probably a 
deleted module). This signal can be resumed with a control link that will be used to retry 
the transfer. 

BoundsFault: signal; 

An attempt has been made to exceed the bounds of a string, array or SubRange (note 
that this includes assigning a negative integer to a cardinal.) in a module that was 
compiled with the /b switch. 

PointerFault: signal; 

An attempt has been made to dereference nil in a module that was compiled with the /n 
switch. 

LinkageFault: error; 

A transfer has been attempted through a port that has not been connected to some other 
port or procedure (the link field of the port was null). 

PortFault: error; 

A transfer has been attempted to a port which is not pending (the frame field of the 
destination port is null). This error is used to handle the startup transients common in a 
configuration of coroutines. 
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ParityError: signal [address: pointer]; 

A parity error has occured in the word pointed to by address. 
PhantomParityError: signal; 

The parity error process was started, but a sweep through memory found no errors. 
StackError: signal [FrameHandle]; 

The stack has either overflowed or underflowed while executing in the designated frame. 
Usually this means that either some code has been smashed or some external link is 
incorrect. 

Fine point: external links may be incorrect because the user forgot to rebind after a recompilation. or 
procedure variables were incorrectly LOOPHOLEd. 



